ci: automate the release — draft notes, sign in CI, publish behind approval

[ndemianc]

Replaces the hybrid model (CI builds unsigned → you sign on your laptop → six gh commands by hand) with three chained workflows. The only manual steps left are the two that need judgement: writing the prose, and deciding to ship.

prepare-release.yml  →  you edit the PR  →  tag-on-merge.yml  →  release.yml
(drafts the notes)      (the prose)         (pushes the tag)     (builds, signs,
                                                                  notarizes, waits)

There is no version file to bump — build-macos.sh derives the version from git describe --tags, so the tag is the version.

Release notes

draft-release-notes.mjs already existed and already did the hard part: it fills in every fact (commit range, PRs, previous tag, suite/case counts, compare URL) and deliberately leaves <!-- TODO --> where judgement is needed. Its own header makes the case: "a changelog auto-generated from commit subjects is the reason most release notes go unread."

So prepare-release.yml opens a PR with that draft instead of committing it, and tag-on-merge.yml refuses to tag while a TODO or the scaffolding block survives — or when the first line doesn't name the version being tagged. The automation can't ship scaffolding, and it can't ship last release's notes either.

Signing

notarize.sh already accepted APPLE_ID + TEAM_ID + APP_SPECIFIC_PASSWORD as the CI alternative to a local keychain profile, so no build script changed. The workflow imports the cert into a temporary keychain in RUNNER_TEMP, runs the existing make-dmg.sh, verifies with codesign + stapler + spctl, and deletes the keychain in an always() step.

Two details are load-bearing and easy to omit:

• set-key-partition-list — without it codesign blocks on a GUI keychain prompt nobody can click, and the job hangs until timeout rather than failing.
• 6h keychain lock timeout — the 5-minute default re-locks during notarization, and the next codesign fails with a misleading "user interaction is not allowed".

Also fetch-depth: 0 on the build checkout: the version stamp comes from git describe --tags, and its failure mode is silent — it warns and ships a build whose About box reads 1.126.0, the Code-OSS base.

The gate

Publishing is deploying (§5): the Squirrel updater installs a published release on every existing install at its next check, no staged rollout, and the rollback pin cannot un-update anyone who already took it.

So the publish job sits in a release Environment with required reviewers. Everything before it is reversible — a branch, a tag, a draft. That step is not. Post-publish it polls the update feed and warns rather than fails, since the release is already correct at that point.

The draft job also refuses to publish unless all four assets are present. Losing only the x64 job would otherwise strand every Intel user silently, because the feed serves per-arch.

Before this can run

Six secrets, listed in RELEASING.md §7 — and one thing that is easy to skip and would quietly defeat the whole design:

Settings → Environments → release → Required reviewers. GitHub creates a missing environment implicitly with no protection rules, so without this the publish job runs straight through and the gate is decorative.

The trade-off, stated

The old §7 described this exact design as the road not taken: "puts your signing identity in the cloud — the hybrid flow above deliberately doesn't." That's now an accepted cost. The doc records what limits the blast radius (temp keychain, always-delete, secrets unavailable to fork PRs), the revocation path, and how to revert to hybrid if you'd rather not hold it.

Verification

actionlint — which shellchecks every run: block — clean on all three workflows.

The notes gate was extracted from the shipped workflow and exercised, so what was tested is what runs:

Input	Expected	Result
Real finished v1.0.4 notes, tagged v1.0.4	pass	✅
Real generated draft (TODOs + scaffolding)	fail	✅ both errors
TODOs removed, scaffolding left	fail	✅
v1.0.4 notes presented as v1.0.5	fail — stale	✅
generate → fill → delete scaffolding	pass	✅

[Copilot]

Pull request overview

Automates the macOS release process end-to-end in GitHub Actions (draft notes → human edits PR → tag on merge → build/sign/notarize → publish behind an Environment approval gate), replacing the previous hybrid “CI builds unsigned, local signing” flow.

Changes:

• Adds a 3-step chained release pipeline via prepare-release.yml, tag-on-merge.yml, and updated release.yml.
• Moves signing/notarization into CI using a temporary keychain and adds an explicit publish approval gate via the release Environment.
• Updates docs/RELEASING.md to document the new workflow, secrets, and operational guardrails.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/RELEASING.md	Replaces the hybrid CI release runbook with the new automated, gated release process and required setup.
.github/workflows/prepare-release.yml	New manual workflow to draft RELEASE-NOTES.md and open a release/vX.Y.Z PR.
.github/workflows/tag-on-merge.yml	New workflow to validate finished notes and push the vX.Y.Z tag on release PR merge.
.github/workflows/release.yml	Updates release workflow to sign/notarize in CI, draft a release with all assets, then publish behind Environment approval.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ndemianc]

All four addressed in 4e4175b. Three were right; one had the right suggestion for the wrong reason.

Tag the merge commit — correct, and the most consequential of the four. base.ref resolves to whatever develop points at when the job starts, so anything merged in the window after the release PR got swept into the tag. Because the build stamps its version from git describe --tags, that ships code the notes don't describe — silently, and only discoverable afterwards. Now ref: ${{ github.event.pull_request.merge_commit_sha }}.

Narrow the TODO gate — correct. Matching the bare word would block a finished release whose prose legitimately says "TODO" (describing a known gap, quoting a code comment), with no fix available except rewording. Now keyed on <!-- TODO, which is the question the gate is actually asking.

Fail fast off develop — correct, and a genuinely nasty failure mode: the PR merges cleanly and then simply never tags. No error, no artifact, just a release that never happens. Now refuses up front, and RELEASING.md §7 shows Use workflow from: develop in the runbook.

list-keychains — changed, but the stated reason isn't right. security accepts unambiguous subcommand prefixes, so the singular form works today:

$ security list-keychain -d user
    "/Users/…/Library/Keychains/login.keychain-db"
$ echo $?
0

So signing would not have failed. Worth fixing regardless: prefix-matching isn't a name, and one more Apple subcommand starting list-keychain… turns it ambiguous. The plural is what security help documents.

Gate re-verified

Six cases, run against the logic extracted from the shipped workflow:

Input	Expected	Result
Real finished v1.0.4 notes @ v1.0.4	pass	✅
Same notes claimed as v1.0.5	fail — stale	✅
Raw generated draft	fail — TODOs + scaffolding	✅
Filled + scaffolding removed	pass	✅
Prose containing the word "TODO"	pass	✅ (blocked before this change)
A real <!-- TODO --> marker	fail	✅

One note on that run: my first attempt reported false failures because the harness invoked draft-release-notes.mjs from outside the repo, where it correctly refuses and writes nothing — so the empty file failed the first-line check for the wrong reason. Harness fixed; the table above is from the corrected run.

actionlint clean.