Make release workflow trigger on version bump merge, not dispatch (#126)

* Start the release when the version-bump PR merges

Releasing took two deliberate acts from the maintainer that were really the
same decision: merge the version-bump PR, then go dispatch `release` with the
same version the PR just landed. The second one carried no new judgement — it
restated the first — but it was the one step that couldn't be done from a
review page, so a release stalled on someone opening the Actions tab.

`release.yml` now also triggers on a push to `main` that touches
`App/Blurt/project.yml`, and a new Linux `resolve` job decides whether that
push is actually a release: it diffs `CFBundleShortVersionString` against the
push's previous commit and checks no `vX.Y.Z` tag exists yet. A project.yml
edit that adds a source file resolves to `release=false` and skips the build
and publish jobs; only a bump landing on main goes through. Running first, on
ubuntu, means a non-release push costs seconds and never reaches the runner
holding the Developer ID key.

The dispatch path stays, and is what re-runs a failed build, republishes, and
does the non-main dry run — `skip_checks`, `skip_smoke`, and `republish` are
dispatch-only inputs, so the merged-bump path always runs the full checks. Both
jobs still pin `github.sha`, so a release is still exactly one reviewed commit,
and publishing still parks on the `release-publish` approval gate.

The `resolve` job supersedes the build job's version guard as the source of the
version; the guard stays as a re-check on the signing runner itself, so the
artifact name and the built binary can't disagree.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F952B3qz1QeXYv5sPGwPh3

* Start release-bump by pushing a marker branch

The last dispatch in the release flow was the first one. Dispatching a workflow
needs the Actions UI or `actions: write`; a chat or web session typically has
neither, but does have push. So the one step that could kick a release off was
the one step an agent couldn't do, and every release still began with the
maintainer opening the Actions tab.

`release-bump.yml` now also triggers on a push of `release/v[0-9]*`. The branch
name is the request — `release/v0.1.37` asks for 0.1.37, with no default_target
guessing, because a marker that named no version would be asking the workflow to
guess what its own name meant. The job checks out main, verifies the marker is
an ancestor of main, bumps on top of main's tip, and force-pushes the result
onto the same branch with the lease pinned to the sha it vetted.

The ancestor check is the load-bearing one. Without it, pushing a branch would
be a way to get a bot-authored commit sitting on top of arbitrary content, and
the PR that followed would quietly be about more than a version bump. With it,
the marker is a signal and the bump is the only commit that lands on it.

This leans on the GITHUB_TOKEN rule in the opposite direction from the rest of
the release path: the bump commit the job force-pushes does not re-fire the push
trigger that started it, which is what keeps it from looping. Noted in the
workflow, RELEASE.md, and the skill's guardrails, since moving this job to a PAT
would silently turn it into a loop.

Dispatch still works, still guards that it came from main, and remains the only
path that accepts an empty version.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F952B3qz1QeXYv5sPGwPh3

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: alexkroman

.claude/skills/release/SKILL.md

@@ -7,8 +7,9 @@ disable-model-invocation: true
 # Releasing Blurt
 
 Everything happens in GitHub Actions, not on this machine — so this works from a
-web or chat session with no terminal. **Confirm the target version with the user
-before dispatching** — publishing is hard to undo.
+web or chat session with no terminal, and without permission to dispatch a
+workflow. **Confirm the target version with the user before starting** —
+publishing is hard to undo.
 
 ## Preconditions (verify first)
 
@@ -23,17 +24,31 @@ before dispatching** — publishing is hard to undo.
 
 ## Steps
 
-1. **Dispatch `release-bump`** with the target version. It runs
+1. **Start `release-bump`.** You almost certainly can't dispatch a workflow (that
+   needs `actions: write`), so push a marker branch instead — it needs only the
+   push you already do:
+
+   ```sh
+   git push origin main:refs/heads/release/v0.1.37
+   ```
+
+   The branch name names the version, and it must carry nothing of its own: the
+   workflow refuses a marker that isn't an ancestor of `main`. It then runs
    `scripts/release-bump.sh` on `macos-26` (marketing version + build number in
-   `App/Blurt/project.yml`, regenerate the project, commit) and pushes
-   `release/vX.Y.Z`.
-2. **Open the PR** for that branch and merge it once green. The workflow does not
-   open it, on purpose: a PR created by `GITHUB_TOKEN` never triggers `check` and
-   so can never merge. Opening it from here works — an agent's own credentials
-   are not `GITHUB_TOKEN`.
-3. **Dispatch `release`** with the same version. The `build` job does the whole
-   Apple path (`xcodebuild` Release → sign nested code → notarize → staple → DMG
-   → verify) and uploads the artifacts.
+   `App/Blurt/project.yml`, regenerate the project, commit) and force-pushes the
+   bump onto that same branch. Dispatching still works if you do have the
+   permission, and only that path accepts an empty version (next patch).
+
+2. **Open the PR** for that branch and hand it to the user to merge. The workflow
+   does not open it, on purpose: a PR created by `GITHUB_TOKEN` never triggers
+   `check` and so can never merge. Opening it from here works — an agent's own
+   credentials are not `GITHUB_TOKEN`.
+3. **Merging it starts `release`** — no dispatch. `release.yml` triggers on a
+   push to `main` touching `project.yml`; its `resolve` job confirms the version
+   changed and isn't already tagged, then the `build` job does the whole Apple
+   path (`xcodebuild` Release → sign nested code → notarize → staple → DMG →
+   verify) and uploads the artifacts. Dispatch `release` by hand only to re-run
+   a failed build, to `republish`, or for a non-`main` dry run.
 4. **Hand the ship gate to the user** — the `publish` job parks on the
    `release-publish` environment. Tell them to download the DMG from the run's
    artifacts, install it, and approve once it works. Nothing is rebuilt after
@@ -42,17 +57,22 @@ before dispatching** — publishing is hard to undo.
 
 **Never approve the `release-publish` deployment yourself**, even though the API
 allows it. The gate exists so a human confirms the real artifact reached users in
-working order; approving a build you dispatched is not a gate. If the user wants
+working order; approving a build you started is not a gate. If the user wants
 unattended releases, that is a deliberate change to the environment's reviewers,
 not something to route around.
 
-Dispatching `release-bump` with no version takes the next patch. There is no
-local orchestrator script — the workflows are the only path.
+There is no local orchestrator script — the workflows are the only path.
 
 ## Guardrails / gotchas
 
-- The workflow is dispatch-only and both jobs pin `github.sha`, so a release can
-  only ever be the exact reviewed commit. Don't add a push/tag trigger.
+- `release.yml`'s only push trigger is `main` + `project.yml` changed, narrowed
+  further by `resolve` (version actually changed, no existing tag), and both jobs
+  pin `github.sha` — so a release can only ever be the exact reviewed commit that
+  carried the bump. Don't widen that trigger, and never add a tag trigger.
+- `release-bump.yml`'s marker trigger is safe only because of its ancestor check
+  (the branch carries nothing of its own) and because a `GITHUB_TOKEN` push
+  doesn't re-fire the trigger. Don't drop either, and don't move that job to a
+  PAT or app token without adding a loop guard.
 - Notarization rejects any nested mach-o/framework lacking a **secure
   timestamp**; the build re-signs frameworks for this reason — don't remove that.
 - The signer-pin (`verify_signer`) checks the produced artifacts against a
@@ -68,4 +88,5 @@ local orchestrator script — the workflows are the only path.
   ref — with the environment restricted to `main`, there is no branch dry run.
 
 Read the script or workflow you're about to run before running it, surface what
-it will do, and get a go-ahead before dispatching.
+it will do, and get a go-ahead before starting it. Pushing a marker branch is as
+consequential as dispatching was — it starts the same pipeline.

.github/workflows/release-bump.yml

@@ -13,13 +13,39 @@ name: release-bump
 # and would sit unmergeable. Opening it from outside Actions — a person, or an
 # agent with its own credentials — makes `check` run normally. The job summary
 # prints a one-click link for that.
+#
+# The same GITHUB_TOKEN rule applies at the other end: merging that PR is what
+# starts `release`, so the merge has to come from outside Actions too. A human
+# clicking Merge, auto-merge, or an agent's own credentials all qualify.
+#
+# Two ways in:
+#
+#  - **Push a marker branch** `release/vX.Y.Z` pointing at `main`, carrying no
+#    commits of its own. The branch name is the request — it names the version —
+#    and pushing a branch is something anyone with repo write can do from a web
+#    or chat session, unlike dispatching a workflow. This is what lets an agent
+#    start a release end to end, leaving the maintainer nothing but the two
+#    approvals (merge the PR, approve the ship gate).
+#  - **Dispatch it**, which additionally accepts an empty version and takes the
+#    next patch itself.
+#
+# The marker-branch path relies on the same GITHUB_TOKEN rule as everything else
+# here, in the opposite direction: the bump commit this job force-pushes onto
+# `release/vX.Y.Z` does NOT re-trigger the push event that started it. That is
+# what keeps this from looping. Don't switch this job to a PAT or an app token
+# without adding a loop guard.
 on:
   workflow_dispatch:
     inputs:
       version:
         description: "Version to bump to (X.Y.Z). Leave empty to take the next patch."
         required: false
         type: string
+  push:
+    branches:
+      # The digit keeps a typo'd branch from spending a macOS runner just to
+      # fail the semver check; that check is still the authority.
+      - "release/v[0-9]*"
 
 # One bump at a time; never cancel one mid-push.
 concurrency:
@@ -43,7 +69,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: blurt
-          ref: ${{ github.sha }}
+          # `main`, not `github.sha`: a bump is always computed against main's
+          # current version, and on the marker-branch path `github.sha` is the
+          # marker, which is a signal rather than the base to bump from.
+          ref: main
           # Tags are what release-bump.sh checks the target version against, and
           # a shallow clone has none — it would miss an existing vX.Y.Z.
           fetch-depth: 0
@@ -53,45 +82,71 @@ jobs:
       - name: Guard the dispatch ref
         # Versions are bumped from main; a bump computed against any other ref
         # would be measured from the wrong current version.
-        if: github.ref != 'refs/heads/main'
+        if: github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main'
         run: |
           echo "::error::release-bump must be dispatched from main (got ${GITHUB_REF})"
           exit 1
 
+      - name: Guard the marker branch
+        # The marker must carry nothing of its own. Otherwise pushing a branch
+        # would be a way to get a bot-authored commit sitting on top of
+        # arbitrary content, and the PR that follows would quietly be about
+        # more than a version bump.
+        if: github.event_name == 'push'
+        working-directory: blurt
+        run: |
+          set -euo pipefail
+          # HEAD is main, from the checkout above.
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" HEAD; then
+            echo "::error::$GITHUB_REF_NAME carries commits that are not on main. Push it at main's tip with nothing of its own. (If it already has the bump commit, this job already ran — open the pull request instead.)"
+            exit 1
+          fi
+          echo "marker $GITHUB_REF_NAME is clean (an ancestor of main)"
+
       - name: Resolve the target version
         id: target
         working-directory: blurt
         # Before the brew install, so a version problem costs seconds rather
         # than minutes. release-bump.sh re-checks all of this; these are the
         # same rules applied early enough to be useful.
         env:
+          EVENT: ${{ github.event_name }}
           INPUT_VERSION: ${{ inputs.version }}
+          BRANCH: ${{ github.ref_name }}
         run: |
           set -euo pipefail
           REPO_ROOT="$PWD"
           # shellcheck disable=SC1091  # sourced at runtime from the checkout
           source scripts/release-lib.sh
 
           main_v="$(require_project_version App/Blurt/project.yml)"
-          version="${INPUT_VERSION:-}"
-          if [ -z "$version" ]; then
-            version="$(default_target "$main_v" "$(latest_release_tag)")" \
-              || die "could not derive a default target from main ($main_v)"
-            info "no version given — defaulting to $version"
+          if [ "$EVENT" = "push" ]; then
+            # The branch name is the request. No default_target on this path:
+            # a marker branch that named no version would be asking the
+            # workflow to guess what its own name meant.
+            version="${BRANCH#release/v}"
+            info "marker branch $BRANCH asks for $version"
+          else
+            version="${INPUT_VERSION:-}"
+            if [ -z "$version" ]; then
+              version="$(default_target "$main_v" "$(latest_release_tag)")" \
+                || die "could not derive a default target from main ($main_v)"
+              info "no version given — defaulting to $version"
+            fi
           fi
           is_semver "$version" || die "version must be X.Y.Z (got: $version)"
 
           run="$(decide_run "$main_v" "$version")" \
             || die "target $version is behind main ($main_v)"
           [ "$run" = "bump" ] \
-            || die "main is already at $version and it has not been released — dispatch the 'release' workflow instead of bumping again"
+            || die "main is already at $version and it has not been released — that bump already landed, so the release has already started from it; check the 'release' workflow's runs rather than bumping again"
 
           # An abandoned release leaves a tag with no release behind it, which
           # burns that version. default_target takes the next patch rather than
           # the next unused one, deliberately: stopping here is better than
           # silently renumbering the release someone asked for.
           if tag_exists_on_origin "v$version"; then
-            die "tag v$version already exists on origin — that version is burned; dispatch again with an explicit higher version"
+            die "tag v$version already exists on origin — that version is burned; start again at an explicit higher version"
           fi
 
           echo "version=$version" >>"$GITHUB_OUTPUT"
@@ -110,19 +165,35 @@ jobs:
       - name: Bump the version
         working-directory: blurt
         env:
+          EVENT: ${{ github.event_name }}
           VERSION: ${{ steps.target.outputs.version }}
         run: |
           set -euo pipefail
           branch="release/v$VERSION"
-          if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+
+          if [ "$EVENT" = "workflow_dispatch" ] \
+            && git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
             echo "::error::branch $branch already exists on origin — delete it or pick another version"
             exit 1
           fi
-          git checkout -b "$branch"
+
+          # -B, not -b: on the marker path the branch already exists on origin,
+          # and this puts the bump on top of main's tip rather than on top of
+          # wherever the marker was pointing.
+          git checkout -B "$branch"
           # Unmodified: it owns the semver / greater-than / tag-collision guards,
           # the project.yml edit, the xcodegen regeneration, and the commit.
           scripts/release-bump.sh "$VERSION"
-          git push -u origin "$branch"
+
+          if [ "$EVENT" = "push" ]; then
+            # The marker is at or behind main, so adding a commit on main's tip
+            # is not always a fast-forward. The lease is pinned to the exact sha
+            # the guard above vetted, so this can only ever overwrite the marker
+            # that started this run — never a commit that arrived since.
+            git push --force-with-lease="$branch:$GITHUB_SHA" origin "HEAD:refs/heads/$branch"
+          else
+            git push -u origin "$branch"
+          fi
 
       - name: Summarize
         env:
@@ -132,10 +203,12 @@ jobs:
           {
             echo "### Bumped to v$VERSION"
             echo
-            echo "Branch \`release/v$VERSION\` pushed. It has no pull request yet —"
-            echo "one opened from inside Actions would never run \`check\`."
+            echo "Branch \`release/v$VERSION\` now carries the bump commit. It has no pull"
+            echo "request yet — one opened from inside Actions would never run \`check\`."
             echo
             echo "[**Open the pull request**](https://github.com/$REPO/compare/main...release/v$VERSION?expand=1)"
             echo
-            echo "Then merge it and dispatch the \`release\` workflow with the same version."
+            echo "Merging it starts the \`release\` workflow by itself — the version landing on"
+            echo "\`main\` is the trigger, so there is nothing left to dispatch. Publishing then"
+            echo "waits on the \`release-publish\` approval once you've tested the DMG."
           } >>"$GITHUB_STEP_SUMMARY"