Push a version tag, let GitHub Actions build the macOS binary and attach it to a release, then publish a formula in your own Homebrew tap so anyone can run brew install you/tap/tool. This is the exact setup I used to ship metalkey, with the two errors that broke the first attempt.
To ship a Swift command-line tool to other Mac users you need three things: a SwiftPM package that builds into a single self-contained binary, a GitHub Actions workflow that builds that binary on a tag push and attaches it to a GitHub Release, and a Homebrew tap, which is a public repository named homebrew-tap holding a formula that downloads the release tarball. You don't need Homebrew core, notarisation or npm for this. The whole loop takes about ten minutes once it's set up, and every later release is a tag push plus a two-line formula change.
I recently pulled a GPU green-screen keyer called metalkey out of a larger project and into its own open-source repository. It's Swift plus Metal, built with SwiftPM, and depends on ffmpeg at runtime. I wanted people to be able to install it with one command, so I set up a release workflow and a tap. The first tag push failed in two seconds, and Homebrew's strict audit flagged things I didn't expect. Below is the setup that works, in the order you build it.
Tested on 11 November 2026 with Swift 6.2 (package tools version 5.9), the GitHub-hosted macos-15 runner, the GitHub CLI (gh) and current Homebrew on an M1 Pro.
Make the binary self-contained
A Homebrew formula that ships a prebuilt binary works best when the release is one executable file and nothing else. SwiftPM resources normally end up in a separate .bundle directory next to the executable, and that bundle gets lost as soon as someone copies or symlinks the binary.
metalkey has a Metal shader file. Instead of shipping it as a bundle resource, I embed it into the binary with .embedInCode, which SwiftPM supports from tools version 5.9:
.embedInCode generates a PackageResources enum with the file's bytes, so swift build -c release produces a single executable with the shader inside it. The shader is compiled at runtime, which also means users don't need the Metal toolchain (xcrun metal) installed.
The platforms line matters as much as the resource. It sets the minimum macOS version baked into the binary, and you'll repeat it in the formula. You can check what a built binary requires with otool -l .build/release/metalkey | grep -A3 LC_BUILD_VERSION, which printed minos 12.0 here.
Two more small things before the workflow: a --help flag that exits with status 0, because both the CI smoke test and the Homebrew test call it, and a licence file, because the formula declares one.
Build and attach the binary on every tag
The release workflow runs only when you push a tag that starts with v. It builds on an Apple Silicon runner, packs the binary with the README and licence into a tarball, writes a SHA-256 checksum, and creates the GitHub Release with the gh CLI that is preinstalled on the runners.
yaml
[]
permissions: contents: write is what allows the built-in github.token to create a release; without it the last step fails with a permission error. The tarball has a single top-level directory named after the version. Homebrew changes into that directory automatically when it unpacks, which keeps the formula's install step to one line.
Release it by tagging and pushing the tag, then wait for the run and check the assets:
bash
git tag v0.1.0
git push origin v0.1.0
gh run watch "$(gh run list --limit 1 --json databaseId -q '.[0].databaseId')" --exit-status
gh release view v0.1.0 --json assets -q '.assets[].name'
"The configuration 'macos-14-arm64-us-default' is not supported"
My first workflow used runs-on: macos-14. The run was marked cancelled after two seconds, with no steps and nothing in the log. The reason only shows up in the run's check annotations:
bash
cs=$(gh api /repos/OWNER/REPO/actions/runs/RUN_ID -q .check_suite_id)
gh api "/repos/OWNER/REPO/check-suites/$cs/check-runs" -q '.check_runs[].id' \
| whileread c; do gh api "/repos/OWNER/REPO/check-runs/$c/annotations" -q '.[].message'; done
That printed The configuration 'macos-14-arm64-us-default' is not supported. GitHub retires old macOS runner images, and a job that targets a retired image is cancelled instead of failing loudly. Switching to macos-15 fixed it. Because no release had been created yet, I deleted the tag and pushed it again on the fixed commit:
If a workflow is ever cancelled instantly with no steps, check the annotations before anything else.
Create the Homebrew tap
A tap is just a GitHub repository whose name starts with homebrew-. If it's called homebrew-tap under your account, users refer to it as you/tap. Formulae live in a Formula/ directory.
Download the release once to get the checksum (or read the .sha256 asset), and check that the downloaded binary actually runs:
# File: Formula/metalkey.rb (in the homebrew-tap repository)class <
desc
homepage
url
sha256
license
depends_on
depends_on
depends_on
bin.install
test
assert_match , shell_output()
depends_on arch: :arm64 stops Intel Macs from installing a binary that can't run there, depends_on macos: :monterey matches the .macOS(.v12) from the package, and depends_on "ffmpeg" pulls in the runtime dependency so users don't have to install it themselves. Homebrew reads the version from the URL, so there's no version line.
Create the repository and push it:
bash
mkdir -p homebrew-tap/Formula && cd homebrew-tap
# add Formula/metalkey.rb and a short README
git init -b main && git add -A && git commit -m "feat: add metalkey 0.1.0"
gh repo create homebrew-tap --public --source . --push
The tap has to be public, otherwise brew can't clone it for other people.
Install, test and audit it like a user would
Test from a clean state, so you're not relying on a tap that's already on your machine:
Installing by the full user/tap/formula name taps the repository and installs in one go. My strict audit failed twice on style, not on substance. First it reported `version 0.1.0` is redundant with version scanned from URL, which is why the formula above has no version line. Then it complained about the order of the depends_on lines, for example . The order that passes is the one in the formula above: , then formula dependencies, then .
If you keep a development build of the tool earlier on your PATH (I symlink mine into ~/.local/bin), Homebrew warns that its executable is shadowed. That's expected on your own machine. Run the brewed copy by its full path (/opt/homebrew/bin/metalkey) when you test, and brew uninstall metalkey afterwards if you want to keep using the development build.
Ship the next version
Every later release is the same three steps:
bash
git tag v0.2.0 && git push origin v0.2.0 # in the tool's repo; the workflow builds and releases
gh release download v0.2.0 -p '*.sha256' -O - # read the new checksum
Then update url and sha256 in Formula/metalkey.rb, commit and push the tap. Users get the new version with brew upgrade.
Which channel to publish to
For a native Apple Silicon tool, the tap is the sweet spot. I skipped npm for metalkey on purpose: nobody looks for a video keyer there, and the package would only exist to download the same binary.
FAQ
Do I need to sign or notarise the binary for Homebrew?
No. Homebrew downloads with curl, which doesn't set the quarantine attribute, and the Swift linker already ad-hoc signs arm64 binaries. You only need notarisation if you want manual downloads to open without Gatekeeper warnings.
Can the formula build from source instead of downloading the binary?
Yes, with depends_on xcode: :build and system "swift", "build", "-c", "release", "--disable-sandbox" in install. It's slower for users and needs Xcode or the Command Line Tools, so I prefer shipping the prebuilt binary and keeping the source build documented in the README.
What about Intel Macs?
Build a second binary on an Intel runner (or a universal binary with swift build -c release --arch arm64 --arch x86_64) and use on_arm / on_intel blocks in the formula with a URL and checksum for each. metalkey depends on Apple Silicon GPU features, so it's arm64 only.
Why did my workflow get cancelled with no logs?
Usually the runner label no longer exists. Read the check-run annotations as shown above; they name the unsupported configuration.
Do I have to name the repository homebrew-tap?
The homebrew- prefix is required; the rest is up to you. homebrew-tools would be installed as you/tools/formula.
Wrapping up
Releasing a Swift CLI comes down to a single self-contained binary, a tag-triggered workflow that attaches it to a GitHub Release, and a small formula in a public homebrew-tap repository. Embedding resources with .embedInCode, matching the minimum macOS version in the package and the formula, and testing with brew audit --strict from a clean tap avoid the problems I ran into, and a retired runner label is the first thing to check when a release run dies instantly. After the first release, each new version is a tag push and a checksum update.
Let me know in the comments if you have questions, and subscribe for more practical development guides.