KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

homebrew-releaser

★ 58 Open GitHub ↗

Release scripts, binaries, and executables directly to Homebrew via GitHub Actions.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Homebrew Releaser

Release scripts, binaries, and executables directly to Homebrew via GitHub Actions.

[![Build](https://github.com/Justintime50/homebrew-releaser/workflows/build/badge.svg)](https://github.com/Justintime50/homebrew-releaser/actions)
[![Coverage Status](https://img.shields.io/codecov/c/github/justintime50/homebrew-releaser)](https://app.codecov.io/github/Justintime50/homebrew-releaser)
[![Version](https://img.shields.io/github/v/tag/justintime50/homebrew-releaser)](https://github.com/justintime50/homebrew-releaser/releases)
[![Licence](https://img.shields.io/github/license/Justintime50/homebrew-releaser)](https://raw.githubusercontent.com/Justintime50/homebrew-releaser/main/LICENSE)

</div>

Homebrew Releaser allows you to release scripts, binaries, and executables directly to a personal Homebrew tap via a GitHub Action. I love what the team at [GoReleaser](https://github.com/goreleaser/goreleaser) did and wanted to replicate that on a smaller and simpler scale for items like shell scripts or other non-go binaries I wanted to distribute.

When you cut a new release when using this GitHub Action, Homebrew Releaser will clone your repo and Homebrew tap on CI, build a `brew audit` compliant Ruby formula file, create a `checksum.txt` file and upload it to your release containing the checksum(s) of your scripts/binaries, and then push the new formula to your Homebrew Tap. If you do not specify a `target` to use, the workflow will use the autogenerated tar archive from GitHub when you created a release, otherwise you can tell Homebrew Releaser which OS and arch pairs you have binaries for. See the accompanying target details below for the URL patterns to follow.

## Usage

**Notes:**

- Shell scripts distributed via Homebrew Releaser **must be executable** and contain a proper shebang to work.
- Homebrew Releaser **will always use the latest release** of a GitHub project. Git release tags must follow semantic versioning for Homebrew to properly infer the installation instructions (eg: `v1.2.0` or `0.3.0`, etc).
- The Homebrew formula filename will match the github repo name.
- It is **highly** recommended to enable debug mode and skip the commit on the first run through to ensure you have configured your workflow correctly and that the generated formula looks the way you want.
- Homebrew Releaser is **not** compatible with monorepos.
- Every precaution will be made to ensure that major releases of this action remain compatible (eg: every release of this action rebuilds and packages the current major release such as `v3` as a convenience to users). If you value stability over convenience, it's highly recommended to pin a specific version or commit hash of this action when using it (eg: `v2.0.1`).
  - Because we pre-build and pin the Docker image used instead of referencing a local Dockerfile, you **cannot** use the `latest` version/tag of this action and expect it to reflect the latest changes.

### GitHub Actions YAML

After you release a project on GitHub, Homebrew Releaser can publish that release to a personal Homebrew tap by updating the project description, version, tar archive url, license, checksum, installation and testing command, and any other required info so you don't have to. You can check the [Homebrew documentation on taps](https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap) and the [formula cookbook](https://docs.brew.sh/Formula-Cookbook) for more details on setting up a Homebrew formula or tap.

#### Minimal Setup

The following is the bare minimum set of parameters required to run Homebrew Releaser (some defaults are assumed):

```yml
# .github/workflows/release.yml
# Start Homebrew Releaser when a new GitHub release is created
on:
  release:
    types: [published]

jobs:
  homebrew-releaser:
    runs-on: ubuntu-latest
    name: homebrew-releaser
    steps:
      - name: Release project to Homebrew tap
        uses: Justintime50/homebrew-releaser@v3
        with:
          # The name of the homebrew tap to publish your formula to as it appears on GitHub (Homebrew taps must start with `homebrew-`).
          # Required - strings
          homebrew_owner: Justintime50
          homebrew_tap: homebrew-formulas

# The Personal Access Token (saved as a repo secret) that has `repo` permissions for the repo running the action AND Homebrew tap you want to release to.
          # Required - string
          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

# Install command for your formula.
          # Required - string
          install: 'bin.install "src/my-script.sh" => "my-script"'
```

#### Complete List of Parameters

The following is the complete list of parameters that are usable with Homebrew Releaser:

```yml
# .github/workflows/release.yml
# Start Homebrew Releaser when a new GitHub release is created
on:
  release:
    types: [published]

# The name of the folder in your homebrew tap where formula will be committed to.
          # Default is shown - string
          formula_folder: Formula

# The branch to push your formula file to (if not used, the branch will be your repo's default branch).
          # Optional - string
          branch: bump_foo_to_v2

# Git author info used to commit to the homebrew tap.
          # Defaults are shown - strings
          commit_owner: homebrew-releaser
          commit_email: homebrew-releaser@example.com

# Install command for your formula.
          # Required - multiline string
          install: 'bin.install "src/my-script.sh" => "my-script"'

# Test command for your formula, used for `brew test`.
          # Optional - multiline string
          test: 'assert_match("my script output", shell_output("my-script-command"))'

# Custom dependencies in case other formulas are needed to build the current one.
          # Optional - multiline string
          depends_on: |
            "bash" => :build
            "gcc"

# Allows you to set a custom download strategy.
          # NOTE: You'll need to implement the strategy and add it to your tap repository.
          # Docs: https://docs.brew.sh/Formula-Cookbook#specifying-the-download-strategy-explicitly
          # Optional - string
          download_strategy: CurlDownloadStrategy

# Allows you to add a custom `require_relative` at the top of the formula template.
          # Optional - string
          custom_require: custom_download_strategy

# Allows you to add custom includes inside the formula class, before dependencies and install blocks.
          # Optional - string
          formula_includes: 'include Language::Python::Virtualenv'

# Run 'brew update-python-resources' on the formula to add Python resources.
          # Docs: https://docs.brew.sh/Python-for-Formula-Authors#python-declarations-for-applications
          # NOTE: This only works with public repositories currently and must be done manually if for a private repo.
          # Default is shown - boolean
          update_python_resources: false

# Override the automatically detected version of a formula with an explicit value.
          # NOTE: This option should only be used if Homebrew cannot automatically detect the version when generating
          # the Homebrew formula. Including this when not necessary could lead to uninstallable formula that may 
          # not pass `brew audit` due to mismatched or redundant version strings.
          # Optional - string
          version: '1.2.0'

# Adds URL and checksum targets for different OS and architecture pairs. Using this option assumes 
          # a tar archive exists on your GitHub repo with the following URL pattern (this cannot be customized):
          # https://github.com/{github_owner}/{repo_name}/releases/download/{tag}/{repo_name}-{version}-{operating_system}-{architecture}.tar.gz'
          # Darwin AMD pre-existing path example: https://github.com/justintime50/myrepo/releases/download/v1.2.0/myrepo-1.2.0-darwin-amd64.tar.gz
          # Linux ARM pre-existing path example: https://github.com/justintime50/myrepo/releases/download/v1.2.0/myrepo-1.2.0-linux-arm64.tar.gz
          # Optional - booleans
          target_darwin_amd64: true
          target_darwin_arm64: false
          target_linux_amd64: true
          target_linux_arm64: false

# Use a custom tarball on your release instead of the auto generated or templated arch URLs listed above.
          # NOTE: Although you can use whatever packaging and naming conventions you want, Homebrew Releaser will look
          # for your tarball at the following URL: https://github.com/{user}/{repo}/releases/download/{release_name}/{custom_tarball}.tar.gz
          # Custom tarball pre-existing path example: https://github.com/justintime50/myrepo/releases/download/v1.2.0/foo.tar.gz
          # Optional - string
          custom_tarball: foo

# Update your homebrew tap's README with a table of all projects in the tap.
          # This is done by pulling the information from all your formula.rb files - eg:
          #
          # | Project                                    | Description  | Install                  |
          # | ------------------------------------------ | ------------ | ------------------------ |
          # | [formula_1](https://github.com/user/repo1) | helpful text | `brew install formula_1` |
          # | [formula_2](https://github.com/user/repo2) | helpful text | `brew install formula_2` |
          # | [formula_3](https://github.com/user/repo3) | helpful text | `brew install formula_3` |
          #
          # Place the following in your README or wrap your project's table in these comment tags:
          # 
          # TABLE HERE
          # 
          #
          # Finally, mark `update_readme_table` as `true` in your GitHub Action config and we'll do the work of building a custom table for you.
          # Default is shown - boolean
          update_readme_table: false

# Skips committing the generated formula to a homebrew tap (useful to verify results on a first run).
          # Default is shown - boolean
          skip_commit: false

# Skips uploading the checksum file for release assets to the release.
          # Default is shown - boolean
          skip_checksum: false

# Logs debugging info to console.
          # Default is shown - boolean
          debug: false

# Ignores non-critical warnings by not raising them at the end and failing the action.
          # Default is shown - boolean
          ignore_warnings: false
```

#### Python Formula

To release a Python package using Homebrew Releaser, one may setup their workflow like so:

```yml
# .github/workflows/release.yml
# Start Homebrew Releaser when a new GitHub release is created
on:
  release:
    types: [published]

jobs:
  homebrew-releaser:
    runs-on: ubuntu-latest
    name: homebrew-releaser
    steps:
      - name: Release my project to my Homebrew tap
        uses: Justintime50/homebrew-releaser@v3
        with:
          homebrew_owner: Justintime50
          homebrew_tap: homebrew-formulas
          github_token: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
          commit_owner: homebrew-releaser
          commit_email: homebrew-releaser@example.com

# Python specific variables
          depends_on: '"python@3.14"'
          install: virtualenv_install_with_resources
          formula_includes: 'include Language::Python::Virtualenv'
          update_python_resources: true
```

## Development

```sh
# Get a comprehensive list of development tools
just --list
```

### Run Manually via Docker

Homebrew Releaser does not clean up artifacts after completing since the temporary Docker image on GitHub Actions will be discarded anyway.

**Note:** All environment variables from above must be prepended with `INPUT_` for the local Docker image (eg: `INPUT_SKIP_COMMIT=true`).

```sh
docker compose up -d --build
```

### Releasing

Releasing Homebrew Releaser takes a few steps, unfortunately to ensure 0 downtime of end-users using the action, it is a manual process:

```sh
# 1. Make all code changes including updating `_version.py`

# 2. Login to Docker if needed
docker login

# 3. Enable buildx in Docker if not already enabled
docker buildx create --use

# 4. Build and push the Homebrew Releaser Docker image and push it to Docker registry
docker buildx build --platform linux/amd64 -t justintime50/homebrew-releaser:3.0.1 --push .

# 5. Update the image version in `action.yml`
# 6. Push the code to GitHub
# 7. Create a `Release` on GitHub matching the version pushed so GitHub Actions marketplace picks it up
```

By following these steps, we push the pre-built Docker image to Docker Hub, we then push our source code to GitHub, we then publish the new version of the Action which references the updated pre-built Docker image (dramatically improves performance by using a pre-built image instead of rebuilding on every run). Users will then either use the stable (eg: v3) tag or an explicit commit hash or version.

homebrew-releaser

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README