Releasing

One tag push does the work. Everything before it is local and reversible; everything after it is public within seconds, so the cheap checks come first.

0. Preflight

git fetch origin
git status --short                      # must print nothing
git log --oneline -1 origin/main        # must equal local main
git worktree list                       # anything here is NOT being released

A release ships main exactly as it stands. Nothing is cherry-picked. If a worktree holds work that belongs in this version, land it first by the new-feature skill step 5 and start over at step 0. Otherwise say out loud which branches are being left out, so "I thought that was in" is caught now rather than by a user.

1. Choose the number

Against the user-visible surface, not the size of the diff. When two rows could apply, take the lower one.

A pre-release carries a - (0.14.0-rc1) and the workflow marks the Release accordingly.

2. Bump VERSION

new=0.13.2
printf '%s\n' "$new" > VERSION
git diff --stat                         # exactly 1 file

VERSION reaches the binary, the .app's Info.plist and the Release title on its own. The README version badges query GitHub's latest release, so they follow the tag pushed in step 5 without an edit — and until that push they keep showing the previous version, which is the truth.

3. Write the changelog

The changelog is the release commit message. There is no CHANGELOG.md. The published notes come from three sources; only the first is yours — the commit list is GitHub's (generate_release_notes: true), and the install instructions already live in .github/workflows/release.yml.

git log --oneline "$(git describe --tags --abbrev=0)"..main

The message answers "does this version affect me?". Lead with the one thing a user would feel; if nothing is observable, say so in a line — that is useful, and "various fixes and improvements" is not. GitHub prints the commit list underneath you, so restating it is wasted.

release: 0.13.1

Documentation, comments and three new build-rule guards. No behaviour change
beyond two help strings that were shipping internal milestone names to users.

The one item a user actually feels is in the skill the tap ships: it named
two streaming commands where there are four, so an agent following it parsed
NDJSON as a single object and failed on the first progress line.

4. Verify, commit, push

make ci                                 # must be green BEFORE the tag exists
git add VERSION
git commit                              # message from step 3
git push origin main

5. Tag and push

The tag is the trigger and the claim about what is being released, so it must equal VERSION.

git tag -a "v${new}" -m "v${new}"
git push origin "v${new}"

6. Watch the workflow

gh run list --workflow=release.yml --limit 1
gh run watch <run-id> --exit-status

Six jobs, about four minutes: verify (checks tag against VERSION and the tap token; gates the rest), cli (darwin/linux/windows tarballs), gui-macos (universal DMG), gui-windows (amd64 and arm64 zips), publish (the Release with every artifact), homebrew (formula, cask and skill to the tap, one commit — skipped, and saying so, when the HOMEBREW_TAP_REPO variable is unset).

7. Check what shipped

A green workflow is a weaker claim than a correct release.

gh release view "v${new}" --json isDraft,isPrerelease -q '.isDraft, .isPrerelease'   # false false
gh release view "v${new}" --json assets -q '.assets[].name' | wc -l                  # 12

Twelve assets: four CLI tarballs (darwin/linux × amd64/arm64), the macOS DMG, a Windows amd64 tarball, two Windows zips, three checksums-*.txt, and manifest.json.

That last one carries the whole Homebrew-less install path, and its absence is the invisible failure: the Release publishes, the tap updates, and only curl … | sh breaks.

curl -fsSL https://raw.githubusercontent.com/dinstein/agent-hub/main/scripts/install.sh \
  | sh -s -- --prefix /tmp/agenthub-check --force
/tmp/agenthub-check/bin/agenthub --version          # ${new}, and must NOT say (dev)
rm -rf /tmp/agenthub-check

--force is not optional here, and it is not loosening anything. The machine cutting a release almost always has agenthub from the tap — the section at the bottom of this file assumes exactly that — and the installer refuses, correctly, to fight another package manager for the name. Without the flag it dies before downloading anything, so the check cannot run on the machine it is written for. The flag is read in one place and only there: it skips that refusal. The install still goes to --prefix, and Homebrew's copy is not touched.

test/installer runs that script end to end against a served release on every make ci; the two lines above are the half it cannot cover — that the real Release holds what the script goes looking for.

Then the tap, a different repository that fails on its own:

for f in Formula/agenthub.rb Casks/agenthub-gui.rb; do
  gh api "repos/dinstein/homebrew-agenthub/contents/${f}" -q .content \
    | base64 -d | grep -E 'version|url|depends_on formula' | head -4
done

The version must be the new one in both — the cask's carries the build hash after a comma — and every url must point at dinstein/agent-hub, not at the tap. Both files land in one commit, so one of them being stale is a bug in tap-sync.sh, not a re-run.

The cask is the only artifact whose install is not exercised by anything in CI. Once per release, on a machine that has not installed it before — a fresh user account is enough, the quarantine flag is per-download and this machine's copies are already cleared:

brew install --cask dinstein/agenthub/agenthub-gui   # pulls the formula with it
open -a AgentHub                                     # must launch with no Gatekeeper prompt
which agenthub && agenthub --version                 # from the formula, and must NOT say (dev)
brew uninstall --cask --zap dinstein/agenthub/agenthub-gui

brew audit --cask --strict --online dinstein/agenthub/agenthub-gui grades the file; only the four lines above grade the install.

When it goes wrong

Rehearse the whole pipeline without a tag via workflow_dispatch: every job runs and publish skips itself.

Not a release: run this checkout where Homebrew installed one

Publishes nothing — no tag, no Release, no tap commit. Use it to exercise a build with a real client before releasing it.

make install-to-brew                     # release-channel build → $(brew --prefix)/bin/agenthub
scripts/install-to-brew.sh --restore     # give the path back to Homebrew

A dirty tree is fine here; the version carries -dirty. A dev-channel binary is refused. Replacing the file does not replace a running daemon: quit and reopen AgentHub if the application is running one, or agenthub daemon restart --headless if an operator is.