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.
| Path | When | What people get |
|---|---|---|
| Developer ID (since 0.6.1) | the nine signing and notarization secrets exist | BenchBar-<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 repository | the 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:
- Bump
MARKETING_VERSIONinmacos/project.ymlandFL_VERSIONinbenchbar. The workflow refuses a tag that does not match both. - Add the
## X.Y.Zsection toCHANGELOG.md. The workflow refuses a version without one, and uses the section as the release notes. - Refresh the screenshots in
docs/imagesfor every screen the release changed, and add new ones where a page still has none:- The Mac first run wizard and the walkthrough:
WizardSnapshotTestsrenders their pages with fixture data, in light and dark (the Snapshots workflow,snapshots.yml, uploads them as an artifact). Use them inquick-start.md,install.mdandapp.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 newwindow-about.png, since General and About moved back into the window in 0.8.1.DocsSnapshotTestsrenders 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).
- The Mac first run wizard and the walkthrough:
- Merge those changes into
next-release, then open a pull request fromnext-releaseintomainand squash merge it (mainkeeps a linear history: one commit per release). auto-tag.ymlchecks thatFL_VERSIONandMARKETING_VERSIONagree and that CHANGELOG.md has the section, tagsvX.Y.Zon that commit, startsrelease.ymlandrelease-windows.ymlfor the tag, and mergesmainback intonext-release. A push tomainthat keeps the version tags nothing. A tag pushed by hand still starts both release workflows.- Wait for the release workflows, open the draft on the Releases page, check the files, publish.
- Publishing starts the Homebrew tap workflow (
homebrew-tap.yml, below). Check that its pull request onaskysh/homebrew-tapmerged.
The version comes from the tag, so the checkout is never edited by CI:
CFBundleShortVersionStringis set from the tag.CFBundleVersionis set from the commit count.- The Windows zips and the tray take the version from the tag too:
main.versionforbenchbar.exe,-p:Versionfor 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:
- 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).
install.ps1 -Version X.Y.Zcannot be tried on a draft (its assets answer 404): download the amd64 zip from the draft instead, unpack it, runbenchbar.exe --shim-versionand startBenchBarTray.exeagainst a distro with a bench.- 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.
- 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 xcodegenscripts/release-local.sh # version from project.yml, Swift tests firstscripts/release-local.sh --skip-testsls 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
- Enroll at developer.apple.com/programs (paid, yearly).
- 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.
- Open Xcode, Settings, Accounts, add your Apple ID.
- Select the team, click Manage Certificates, click +, choose Developer ID Application.
- Open Keychain Access, find “Developer ID Application: Your Name
(TEAMID)”, right click, Export, save as
.p12with a strong password. - 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.
- Open App Store Connect, Users and Access, Integrations, App Store Connect API, Team Keys.
- Generate a key with the Developer role.
- 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 --sparkletools="$(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 CIThe 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.
| File | Installs | Updated for |
|---|---|---|
Formula/benchbar.rb | the CLI, from benchbar-cli-<version>.tar.gz | every release |
Casks/benchbar-app.rb | BenchBar.app, from the DMG; depends on the formula | signed 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 appbrew install askysh/tap/benchbar # CLI onlyBoth 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:
| Secret | Value |
|---|---|
MACOS_CERTIFICATE_P12 | the .p12 from step 2, base64: base64 -i cert.p12 | pbcopy |
MACOS_CERTIFICATE_PASSWORD | its password |
MACOS_SIGN_IDENTITY | Developer ID Application: Your Name (TEAMID) |
APPLE_TEAM_ID | the Team ID |
NOTARY_API_KEY_P8 | the .p8 from step 3, base64 |
NOTARY_API_KEY_ID | its Key ID |
NOTARY_API_ISSUER_ID | its Issuer ID |
SPARKLE_ED_PRIVATE_KEY | the contents of sparkle_ed.key |
SPARKLE_ED_PUBLIC_KEY | the public key generate_keys printed |
HOMEBREW_TAP_TOKEN | the 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=TEAMIDexport 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, versionscripts/macos-release.sh 0.3.0 # NOTARY_TIMEOUT=2h for a slow first notarizationgh release create v0.3.0 dist/* --title "BenchBar 0.3.0" --draftWhat each step does, and why
Ad hoc path (scripts/release-local.sh)
- Build with
scripts/macos-build.sh, version and build number from the environment, thencodesign --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. - Zip with
ditto -c -k --keepParent, the form macOS expects for app bundles (resource forks and symlinks survive). - DMG with
hdiutil create, holding the app and an Applications shortcut for drag and drop. - SHA256SUMS with
shasum -a 256.install.shchecks the zip against it before unpacking.
Developer ID path (scripts/macos-release.sh)
- Build and sign (
scripts/macos-build.sh --sparklewithBENCHBAR_SIGN_IDENTITYset). xcodebuild signs the app and Sparkle’s helpers with the Developer ID, the Hardened Runtime and a secure timestamp. Notarization requires all three. - Notarize the app.
xcrun notarytool submit ... --waituploads a zip to Apple, which scans it and returns a ticket. Takes minutes. - Staple.
xcrun stapler staple BenchBar.appattaches the ticket to the app, so Gatekeeper accepts it offline. The app is zipped again after stapling; that zip is the Sparkle download. - DMG.
hdiutil createmakes 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. - Appcast.
generate_appcastreads the zip, signs it with the EdDSA key and writesappcast.xmlwith the download URL on the GitHub release. The app’sSUFeedURLpoints athttps://github.com/askysh/benchbar/releases/latest/download/appcast.xml, so the newest release’s feed is always the one read. - Cask. The template gets the version and the DMG’s sha256, and a
pull request is opened on the tap when
HOMEBREW_TAP_TOKENexists.
Sparkle in the app
- Off by default.
scripts/macos-build.shbuilds 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(orBENCHBAR_SPARKLE=YES) makes XcodeGen includemacos/sparkle.yml: the Sparkle 2 package, theSPARKLEcompilation condition, andSUFeedURL,SUPublicEDKeyandSUEnableAutomaticChecksin Info.plist.macos/BenchBar/Updates/Updater.swiftstarts Sparkle’s standard updater and adds Check for Updates… to the right click menu and the app menu.BENCHBAR_APPCAST_URLoverrides 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.appspctl --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 onlyshasum -a 256 -c dist/SHA256SUMSNot in scope
- The Mac App Store: BenchBar has to run the
benchbarCLI, which a sandboxed app cannot do. - Intel builds: the app is Apple Silicon only (
ARCHS = arm64).