Skip to content

Releasing BenchBar

One workflow, .github/workflows/release.yml, two paths. It runs when a v* tag is pushed and drafts a GitHub release with the files below. You review the draft and publish it.

PathWhenWhat people get
Developer ID (since 0.6.1)the nine signing and notarization secrets existBenchBar-<version>.zip, BenchBar-<version>.dmg and SHA256SUMS, signed, notarized and stapled, plus appcast.xml for Sparkle and benchbar-cli-<version>.tar.gz for the Homebrew formula
Ad hoc (up to 0.6.0)no Apple Developer secrets in the repositorythe same zip, dmg, CLI tarball and SHA256SUMS, ad hoc signed. A DMG download showed “Apple could not verify” once (the install page keeps the Open Anyway steps for those releases); install.sh downloads with curl, which sets no quarantine flag, so the app opened directly.

The check job decides: it looks for the secrets and prints which path runs as a notice. Nothing else differs for you: same tag, same draft release.

Branches

Work lands on next-release: every pull request targets it. main moves only when a release is cut, so it always holds the last release, and so do the one line installers and the docs site, which read from main. A push to main with a new version tags it and starts the release builds (auto-tag.yml).

Cutting a release

On next-release, then into main:

  1. Bump MARKETING_VERSION in macos/project.yml and FL_VERSION in benchbar. The workflow refuses a tag that does not match both.
  2. Add the ## X.Y.Z section to CHANGELOG.md. The workflow refuses a version without one, and uses the section as the release notes.
  3. Refresh the screenshots in docs/images for every screen the release changed, and add new ones where a page still has none:
    • The Mac first run wizard and the walkthrough: WizardSnapshotTests renders their pages with fixture data, in light and dark (the Snapshots workflow, snapshots.yml, uploads them as an artifact). Use them in quick-start.md, install.md and app.md.
    • The Windows first run wizard: take the screenshots on a Windows PC and use them in windows.md.
    • The BenchBar window panes: window-general.png, and a new window-about.png, since General and About moved back into the window in 0.8.1. DocsSnapshotTests renders the window panes, the Find User sheet and three wizard pages in a real key window (the window panes are captured as the window server draws them, so the sidebar and the selection look as in the app).
  4. Merge those changes into next-release, then open a pull request from next-release into main and squash merge it (main keeps a linear history: one commit per release).
  5. auto-tag.yml checks that FL_VERSION and MARKETING_VERSION agree and that CHANGELOG.md has the section, tags vX.Y.Z on that commit, starts release.yml and release-windows.yml for the tag, and merges main back into next-release. A push to main that keeps the version tags nothing. A tag pushed by hand still starts both release workflows.
  6. Wait for the release workflows, open the draft on the Releases page, check the files, publish.
  7. Publishing starts the Homebrew tap workflow (homebrew-tap.yml, below). Check that its pull request on askysh/homebrew-tap merged.

The version comes from the tag, so the checkout is never edited by CI:

  • CFBundleShortVersionString is set from the tag.
  • CFBundleVersion is set from the commit count.
  • The Windows zips and the tray take the version from the tag too: main.version for benchbar.exe, -p:Version for the tray.

The Windows zips

The same tag starts release-windows.yml. It builds benchbar.exe (Go) and the tray app (framework dependent .NET 10) for x64 and Arm64, packs benchbar-windows-X.Y.Z-amd64.zip and -arm64.zip (both programs, the tray’s files, README.txt and a SHA256SUMS inside), and attaches them with benchbar-windows-X.Y.Z-SHA256SUMS.txt to the draft that release.yml creates for the tag. On a tag push it waits up to 130 minutes for that draft (the Mac job allows 120) and creates one only if none appears; a manual run attaches only to an existing draft. The sums file must not end in SHA256SUMS: install.sh picks the first asset with that ending for the Mac app. The workflow never publishes. Re-run it after a re-run of release.yml, which replaces the notes and with them the Windows paragraph.

The signing step is dormant: it runs only when SIGNPATH_API_TOKEN and SIGNPATH_ORGANIZATION_ID are set (repo secrets; there are none today, so every Windows program ships unsigned; SIGNPATH_PROJECT_SLUG, SIGNPATH_SIGNING_POLICY_SLUG and SIGNPATH_ARTIFACT_CONFIGURATION_SLUG variables override benchbar, release-signing and windows-exe), the project’s own exe and DLLs (not NuGet packages) go through SignPath, only for a tag build, and each is checked with Get-AuthenticodeSignature. A missing secret, a failed request or a signature that does not check leaves that exe unsigned; the release still completes, and its notes say which binaries are unsigned. To make a release fail instead when a program of ours is unsigned, set the repository variable SIGNING_REQUIRED to true. It is unset today; set it only once signing works, or no Windows release can be attached.

The release job also attests both zips with actions/attest-build-provenance (it needs the id-token and attestations write permissions), so gh attestation verify benchbar-windows-X.Y.Z-amd64.zip -R askysh/benchbar works. The notes and README.txt tell users to run the one liner as & ([scriptblock]::Create((irm URL))) -Version X.Y.Z, which pins the version and sets nothing in their session. A build that is not a release points at main instead of a tag.

Before publishing the draft, check:

  1. Both zips and the sums file are attached, and the Windows paragraph of the notes names the unsigned binaries (all of them while there are no signing secrets).
  2. install.ps1 -Version X.Y.Z cannot be tried on a draft (its assets answer 404): download the amd64 zip from the draft instead, unpack it, run benchbar.exe --shim-version and start BenchBarTray.exe against a distro with a bench.
  3. After publishing, run the one liner from Windows on a clean Windows 11 (a VM or Windows Sandbox) and check these:
    • One line installer: no dialog is expected.
    • Zip route (unpack, start a program yourself): the “Open File - Security Warning” is expected until the builds are signed.
    • Smart App Control on: the installer stops before it writes anything.
  4. Submit the two zips at https://www.microsoft.com/wdsi/filesubmission as a software developer when Defender flags them. This is a manual step for each release.

To try the Windows build without a release, run Release Windows by hand with a version and draft_release off: the zips land as workflow artifacts only. A pull request that changes release-windows.yml or install.ps1 builds both zips and runs the installer on windows-latest.

To give testers a build before a release: run Release Windows by hand from main with a version such as 0.8.0 and draft_release off, then download the windows-amd64 (and windows-arm64) artifact from the run’s summary page. Each holds the zip and its sums-<arch>.txt. Send the zip; the tester unpacks it and runs its own install.ps1, as Windows describes. The programs are unsigned, so starting one from the unpacked folder shows the Open File security warning and Smart App Control in enforce mode blocks them: testers need it off or in evaluation mode.

Trying a build without a release

Every pull request run of CI (ci.yml, job “Unsigned release bundle”) uploads the same zip, dmg and SHA256SUMS as a workflow artifact named BenchBar-unsigned-<sha>: open the run on the Actions tab, scroll to Artifacts, download. Locally, the same files come from:

brew install xcodegen
scripts/release-local.sh # version from project.yml, Swift tests first
scripts/release-local.sh --skip-tests
ls dist/

release-local.sh needs full Xcode, XcodeGen and nothing else. It is the ad hoc path of the workflow, running on your Mac.

The Developer ID path: one time setup

Everything below switches on when the secrets exist; the repository has had all nine since 0.6.1. Without them the workflow takes the ad hoc path.

1. Apple Developer Program

  1. Enroll at developer.apple.com/programs (paid, yearly).
  2. Note the Team ID (10 characters) under Membership details.

2. A Developer ID Application certificate

This is the certificate for apps distributed outside the Mac App Store.

  1. Open Xcode, Settings, Accounts, add your Apple ID.
  2. Select the team, click Manage Certificates, click +, choose Developer ID Application.
  3. Open Keychain Access, find “Developer ID Application: Your Name (TEAMID)”, right click, Export, save as .p12 with a strong password.
  4. The identity string is that exact name: Developer ID Application: Your Name (TEAMID). Check it with:
    security find-identity -v -p codesigning

3. An App Store Connect API key for notarization

notarytool uses an API key instead of your Apple ID password.

  1. Open App Store Connect, Users and Access, Integrations, App Store Connect API, Team Keys.
  2. Generate a key with the Developer role.
  3. Download AuthKey_<KEYID>.p8 (only possible once) and note the Key ID and the Issuer ID shown on that page.

4. Sparkle EdDSA keys

Sparkle checks that every update was signed by you. The tools come with the Sparkle package, fetched by the first Sparkle build:

scripts/macos-build.sh --sparkle
tools="$(dirname "$(find macos/build/DerivedData/SourcePackages/artifacts -name generate_keys | head -n 1)")"
"$tools/generate_keys" # creates the key in your login keychain, prints the public key
"$tools/generate_keys" -x sparkle_ed.key # exports the private key to a file, for CI

The public key goes into the app (SUPublicEDKey). The private key signs updates; keep it in your password manager and as a CI secret, never in the repo. Losing it means existing installs can no longer update, so back it up.

5. The Homebrew tap

askysh/homebrew-tap holds two benchbar files, both written by .github/workflows/homebrew-tap.yml when a release is published. The tap also holds the cask of Margin, which its own workflow updates.

FileInstallsUpdated for
Formula/benchbar.rbthe CLI, from benchbar-cli-<version>.tar.gzevery release
Casks/benchbar-app.rbBenchBar.app, from the DMG; depends on the formulasigned releases (those with appcast.xml)

The workflow runs on publish, not with the draft: a draft’s download URLs answer 404, so a formula merged earlier would break brew install. It downloads the release’s tarball and DMG, checks them against SHA256SUMS, renders the formula and cask from packaging/homebrew with scripts/homebrew-render.sh, runs brew style and brew audit --strict --online, installs both, runs brew test, uninstalls, and opens a pull request on the tap that merges itself once the tap’s checks pass. It also closes the open tap pull requests of older benchbar versions. The tap’s tests check audits, installs and uninstalls only the files a pull request changes. Thus a Margin release at the same time does not block a benchbar release. A prerelease leaves the tap alone. Run it by hand from the Actions tab (Homebrew tap, Run workflow, the version) to redo one.

It needs HOMEBREW_TAP_TOKEN: a fine grained personal access token with Contents and Pull requests write access to askysh/homebrew-tap only. Without it the workflow still checks everything and prints the two files to copy by hand. The tap repository needs auto-merge allowed (Settings, General) and its tests check required on main, or the pull request waits for you.

People then install with:

brew install askysh/tap/benchbar askysh/tap/benchbar-app # CLI and app
brew install askysh/tap/benchbar # CLI only

Both names are typed because Homebrew only trusts a third party tap for the names given on the command line; the cask alone would be refused its formula. Since 0.7.1 the app also carries its own copy of the CLI (the same files as the formula’s tarball, copied in by scripts/app-embed-cli.sh when the app is built), and the formula’s benchbar hands off to it. The formula still stands on its own, so it works on Intel Macs too while the cask is Apple silicon only.

Pull requests that change the CLI or packaging/homebrew also run homebrew-formula.yml, which builds the tarball from the checkout, installs it from a throwaway local tap with a file:// url, and runs the CLI in an empty HOME; it runs nightly too, since brew itself changes. It is not a required check.

The official homebrew/cask needs a notable, notarized app with some history; submit there once BenchBar qualifies (roadmap v1.0).

Secrets

Add these in the GitHub repository, Settings, Secrets and variables, Actions:

SecretValue
MACOS_CERTIFICATE_P12the .p12 from step 2, base64: base64 -i cert.p12 | pbcopy
MACOS_CERTIFICATE_PASSWORDits password
MACOS_SIGN_IDENTITYDeveloper ID Application: Your Name (TEAMID)
APPLE_TEAM_IDthe Team ID
NOTARY_API_KEY_P8the .p8 from step 3, base64
NOTARY_API_KEY_IDits Key ID
NOTARY_API_ISSUER_IDits Issuer ID
SPARKLE_ED_PRIVATE_KEYthe contents of sparkle_ed.key
SPARKLE_ED_PUBLIC_KEYthe public key generate_keys printed
HOMEBREW_TAP_TOKENthe tap token from step 5; without it the tap is updated by hand

The check job needs the first nine. With any missing it says which and takes the ad hoc path.

Locally, without CI

With the certificate in your keychain and the keys on disk:

export BENCHBAR_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
export BENCHBAR_TEAM_ID=TEAMID
export NOTARY_KEY_PATH=~/keys/AuthKey_ABC123.p8 NOTARY_KEY_ID=ABC123 NOTARY_ISSUER_ID=...
export SPARKLE_ED_KEY_PATH=~/keys/sparkle_ed.key BENCHBAR_SPARKLE_PUBLIC_KEY=...
scripts/macos-release.sh --check # tools, settings, identity, version
scripts/macos-release.sh 0.3.0 # NOTARY_TIMEOUT=2h for a slow first notarization
gh release create v0.3.0 dist/* --title "BenchBar 0.3.0" --draft

What each step does, and why

Ad hoc path (scripts/release-local.sh)

  1. Build with scripts/macos-build.sh, version and build number from the environment, then codesign --force --deep -s -. An ad hoc signature satisfies Apple Silicon’s requirement that every binary is signed, but carries no identity, so Gatekeeper cannot trust it.
  2. Zip with ditto -c -k --keepParent, the form macOS expects for app bundles (resource forks and symlinks survive).
  3. DMG with hdiutil create, holding the app and an Applications shortcut for drag and drop.
  4. SHA256SUMS with shasum -a 256. install.sh checks the zip against it before unpacking.

Developer ID path (scripts/macos-release.sh)

  1. Build and sign (scripts/macos-build.sh --sparkle with BENCHBAR_SIGN_IDENTITY set). xcodebuild signs the app and Sparkle’s helpers with the Developer ID, the Hardened Runtime and a secure timestamp. Notarization requires all three.
  2. Notarize the app. xcrun notarytool submit ... --wait uploads a zip to Apple, which scans it and returns a ticket. Takes minutes.
  3. Staple. xcrun stapler staple BenchBar.app attaches the ticket to the app, so Gatekeeper accepts it offline. The app is zipped again after stapling; that zip is the Sparkle download.
  4. DMG. hdiutil create makes a compressed disk image holding the app and an Applications shortcut. The DMG is signed, notarized and stapled too, so the first open shows no warning.
  5. Appcast. generate_appcast reads the zip, signs it with the EdDSA key and writes appcast.xml with the download URL on the GitHub release. The app’s SUFeedURL points at https://github.com/askysh/benchbar/releases/latest/download/appcast.xml, so the newest release’s feed is always the one read.
  6. Cask. The template gets the version and the DMG’s sha256, and a pull request is opened on the tap when HOMEBREW_TAP_TOKEN exists.

Sparkle in the app

  • Off by default. scripts/macos-build.sh builds without Sparkle; the app then contains no update code and makes no network requests. The ad hoc path never includes it: Sparkle needs signed updates to be safe.
  • scripts/macos-build.sh --sparkle (or BENCHBAR_SPARKLE=YES) makes XcodeGen include macos/sparkle.yml: the Sparkle 2 package, the SPARKLE compilation condition, and SUFeedURL, SUPublicEDKey and SUEnableAutomaticChecks in Info.plist.
  • macos/BenchBar/Updates/Updater.swift starts Sparkle’s standard updater and adds Check for Updates… to the right click menu and the app menu.
  • BENCHBAR_APPCAST_URL overrides the feed URL (for a test feed).

Checking a build

codesign -dv --verbose=2 macos/build/BenchBar.app # ad hoc: "Signature=adhoc"
codesign --verify --deep --strict --verbose=2 macos/build/BenchBar.app
spctl --assess --type execute --verbose=2 macos/build/BenchBar.app # Developer ID: "source=Notarized Developer ID"
xcrun stapler validate dist/BenchBar-0.3.0.dmg # Developer ID only
shasum -a 256 -c dist/SHA256SUMS

Not in scope

  • The Mac App Store: BenchBar has to run the benchbar CLI, which a sandboxed app cannot do.
  • Intel builds: the app is Apple Silicon only (ARCHS = arm64).