fix: make dev->main promotion push succeed via bypass-actor App token (#49)

The nightly promote fast-forwards main to a fully-green dev HEAD, but the
push (as github-actions[bot]) is rejected by the main ruleset: it requires
PRs + a status check and the default token is not a bypass actor, so a
direct ref push can never land regardless of fast-forwardability. The
prior comment claiming protection 'only rejects non-FF' was wrong.

Mint a GitHub App installation token (actions/create-github-app-token,
SHA-pinned) and push with it; the App must be added to the main ruleset's
bypass actors out-of-band. The promoted commit already passed every check
on dev (gated by check-dev-green.sh), so re-gating it via a PR on main is
redundant.

Also fix a gate self-poison: a stale failed 'promote' check-run from a
prior run on the same dev HEAD blocked every subsequent gate run (it was
excluded only by the current run_id). Exclude prior promote check-runs
too, scoped to name=='promote' AND a /actions/runs/ details_url so an
external app cannot hide a real failing check by naming it 'promote'; the
positive REQUIRED_CHECKS allow-list stays authoritative.

Gates: GPT-4.1 cross-review APPROVE (no security regression). Unit-tested:
stale promote ignored -> PASS; real failure / external promote / missing
required check -> BLOCK. shellcheck clean (also fixed a pre-existing
SC2295 on the run_id match).

.github/scripts/check-dev-green.sh

@@ -26,6 +26,11 @@
 set -euo pipefail
 
 EXCLUDE_RUN_ID="${EXCLUDE_RUN_ID:-}"
+# Name of the promotion workflow's own check-run (its job id). STALE check-runs from
+# prior FAILED promote runs on the same dev HEAD are dropped in the loop so they don't
+# self-poison the "every present check must be green" rule. Configurable so a job
+# rename doesn't silently break the exclusion.
+PROMOTE_CHECK_NAME="${PROMOTE_CHECK_NAME:-promote}"
 # Mandatory checks (one per line). Defaults to the CI suite, which runs on
 # every push to dev (see ci.yml). Keep in sync with those job names; if a name
 # drifts the gate blocks (fails safe) until the list is updated.
@@ -41,7 +46,18 @@ while IFS=$'\037' read -r name status conclusion details_url; do
   [ -n "${name:-}" ] || continue
   # drop the promotion run's own check-run by run id (never by name).
   if [ -n "${EXCLUDE_RUN_ID}" ] && \
-     [ "${details_url}" != "${details_url#*/runs/${EXCLUDE_RUN_ID}/}" ]; then
+     [ "${details_url}" != "${details_url#*/runs/"${EXCLUDE_RUN_ID}"/}" ]; then
+    continue
+  fi
+  # Also drop ANY check-run from the promotion workflow itself — not just THIS run
+  # (above) but STALE ones left by prior FAILED promote runs on the same dev HEAD,
+  # which would otherwise self-poison this gate forever (the failure check-run is
+  # immutable on the commit). Scoped to name==PROMOTE_CHECK_NAME AND a GitHub Actions
+  # run URL (details_url under /actions/runs/) so an EXTERNAL app cannot hide a real
+  # failing check by naming it "promote". The positive REQUIRED_CHECKS allow-list
+  # below is the authoritative signal regardless — "promote" is never a required check.
+  if [ "${name}" = "${PROMOTE_CHECK_NAME}" ] && \
+     [ "${details_url}" != "${details_url#*/actions/runs/}" ]; then
     continue
   fi
   seen=$((seen + 1))

.github/workflows/promote-dev-to-prod.yml

@@ -19,15 +19,32 @@ jobs:
       contents: write
       checks: read
     steps:
+      # Mint a GitHub App installation token for the protected-branch push below.
+      # A plain ref push by github-actions[bot] is REJECTED by the `main` ruleset
+      # (PRs required + a required status check; the default token is not a bypass
+      # actor). The App behind these secrets MUST be added to the `main` ruleset's
+      # bypass actors; the push is then accepted and attributed to the App (not a
+      # human PAT). The promoted commit already passed every check on dev (gated
+      # below), so re-gating it via a PR on main would be redundant.
+      - name: Mint app token for the protected-branch push
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.PROMOTE_APP_ID }}
+          private-key: ${{ secrets.PROMOTE_APP_PRIVATE_KEY }}
       - uses: actions/checkout@v7
         with:
           ref: dev
           fetch-depth: 0
+          # Persist the App token as the git credential so the fast-forward push uses
+          # the bypass-actor identity (not the default github-actions[bot]).
+          token: ${{ steps.app-token.outputs.token }}
       - name: Require dev HEAD fully green
         # Hard precondition: every check-run on the dev HEAD commit must be
         # completed + passing before we let it become prod. A red OR still-pending
-        # check blocks the promotion. The promote job's own in-progress check-run
-        # is excluded by name so the gate can't deadlock on itself.
+        # check blocks the promotion. The promotion workflow's OWN check-runs are
+        # excluded by the gate (this run by id, plus any STALE prior promote runs by
+        # name + Actions URL) so the gate can't deadlock on itself.
         env:
           GH_TOKEN: ${{ github.token }}
           # exclude THIS run's own check-run by its run id (not by name).
@@ -39,7 +56,13 @@ jobs:
             -q '.check_runs[] | [.name, .status, (.conclusion // ""), (.details_url // "")] | join("\u001f")' \
             | bash .github/scripts/check-dev-green.sh
       - name: Fast-forward main (PROD) to dev
-        # main is the production branch; a plain ref push is fast-forward-only
-        # (branch protection rejects non-FF), so a diverged main fails loudly.
+        # main is the production branch. A direct ref push is normally rejected by the
+        # `main` ruleset (PRs required), so this succeeds only because the App minted
+        # above is a bypass actor. The push is fast-forward-only, so a diverged main
+        # fails loudly rather than force-updating.
+        #
+        # SECURITY: this is the LAST step on purpose. The App token persists as the
+        # git credential after checkout — do not add steps after this push that run
+        # untrusted code or could echo the credential.
         run: |
           git push origin HEAD:refs/heads/main