fix(ci): make promotion and review decisions fail safely (#1843)

Author: FelixTJDietrich

.github/actions/setup-caches/action.yml

@@ -36,8 +36,7 @@ runs:
         fi
         echo "dependencies=$DEPENDENCY_HASH" >> "$GITHUB_OUTPUT"
         echo "generated-clients=$GENERATED_CLIENTS_HASH" >> "$GITHUB_OUTPUT"
-        # Only default-branch runs write caches: a cache saved on any other ref is invisible to every
-        # other ref, so a pull-request write would never be reused.
+        # Publish default-branch caches for reuse across PRs, rather than PR-scoped entries.
         if [[ "$GITHUB_REF" == "refs/heads/$DEFAULT_BRANCH" && "$GITHUB_EVENT_NAME" =~ ^(push|schedule|workflow_dispatch)$ ]]; then
           echo "save=true" >> "$GITHUB_OUTPUT"
         else

.github/actions/setup-toolchain/action.yml

@@ -12,12 +12,9 @@ runs:
       shell: bash
       run: |
         echo "version=$(jq -r '.devEngines.packageManager.version' package.json)" >> "$GITHUB_OUTPUT"
-        # On Windows this shell is Git Bash, whose $HOME is an MSYS path that the Windows PATH
-        # cannot resolve. os.homedir() is what both pnpm/setup and actions/cache's `~` expand to, so
-        # asking Node keeps the destination, the cache path and PATH the same directory everywhere.
+        # Use the native home directory, not Git Bash's MSYS path, on Windows.
         echo "dest=$(node -p 'require("node:path").join(require("node:os").homedir(), "setup-pnpm")')" >> "$GITHUB_OUTPUT"
-    # The path is pnpm/setup's own default destination, so the action does not restate it as `dest`;
-    # the version check below fails the job if that default ever moves.
+    # Cache pnpm/setup's default installation directory.
     - id: pnpm-cache
       uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
       with:
@@ -78,14 +75,12 @@ runs:
         cache-dependency-path: pnpm-lock.yaml
         install: false
         require-lockfile: true
-    # A cache key cannot be overwritten, so one truncated save would poison every job until the pin
-    # moves. Answering here proves the restored tree and the PATH it was reached through, and holds
-    # the freshly installed tree to the pin before it is offered to anyone else.
+    # Cache entries are immutable: validate the executable before publishing a new entry.
     - shell: bash
       env:
         PNPM_VERSION: ${{ steps.pnpm.outputs.version }}
       run: test "$(pnpm --version)" = "$PNPM_VERSION"
-    # A cache saved on any ref other than the default branch is invisible to every other ref.
+    # Default-branch caches are reusable across PRs; merge-ref caches are scoped to that PR.
     - if: steps.pnpm-cache.outputs.cache-hit != 'true' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
       uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
       with:

.github/workflows/continuous-staging.yml

@@ -1,13 +1,4 @@
-# Moves the environment that follows the default branch to every commit CI has built.
-#
-# Releases are how production is promoted: they carry a version, a provenance manifest and a signed
-# lock, and a person decides when one is cut. Staging exists to be the branch as it stands, so it
-# follows commits instead — the promotion workflow is still the only thing that writes a channel, so
-# the identity a host pins does not change.
-#
-# There is no switch for this. An environment that sometimes follows the branch and sometimes runs a
-# release is two environments wearing one name, and the channel already has the only hold that
-# matters: `freeze`, which is signed and travels with the channel rather than sitting beside it.
+# Promotes successful main builds through the environment-protected promotion workflow.
 name: Continuous staging
 
 on:
@@ -19,49 +10,28 @@ on:
 permissions: {}
 
 concurrency:
-  # Not cancel-in-progress: a superseded promotion has already written its channel, and the next one
-  # supersedes it on the host anyway.
+  # Let the current run finish observing the promotion it dispatched.
   group: continuous-staging
   cancel-in-progress: false
 
 jobs:
   follow-main:
-    # A red build is not something to deploy, and a run that was cancelled decided nothing.
     if: >-
       ${{ github.event.workflow_run.conclusion == 'success'
         && github.event.workflow_run.event == 'push' }}
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
       actions: write # dispatch the promotion workflow
-      contents: read # read the channel to honour a freeze
     steps:
       - name: Follow this commit on staging
         env:
           GH_TOKEN: ${{ github.token }}
           COMMIT: ${{ github.event.workflow_run.head_sha }}
         run: |
           set -euo pipefail
-          # A hold has to survive the next green build, or it is advice rather than a hold. The
-          # channel is the record of it, so it is what gets asked.
-          frozen=$(gh api "repos/$GITHUB_REPOSITORY/contents/channels/staging.json?ref=deploy-state" \
-            --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | jq -r '.freeze // false' || echo false)
-          if [ "$frozen" = true ]; then
-            echo "::notice::staging is frozen; leaving it where it is"
-            exit 0
-          fi
-
-          since=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-          gh workflow run promote.yml --repo "$GITHUB_REPOSITORY" \
-            -f environment=Staging -f commit="$COMMIT"
-          # The dispatch returns before the run exists, and taking the newest run blindly could
-          # watch someone else's promotion, so the run is matched on being newer than the request.
-          for _ in $(seq 1 30); do
-            run=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow promote.yml --limit 10 \
-              --json databaseId,createdAt \
-              --jq "[.[] | select(.createdAt > \"$since\")] | sort_by(.createdAt) | .[0].databaseId // empty")
-            [ -n "$run" ] && break
-            sleep 5
-          done
-          [ -n "$run" ] || { echo "::error::promote.yml did not start"; exit 1; }
+          run=$(gh api --method POST "repos/$GITHUB_REPOSITORY/actions/workflows/promote.yml/dispatches" \
+            -f ref=main -f 'inputs[environment]=Staging' -f "inputs[commit]=$COMMIT" \
+            -f 'inputs[automatic]=true' -F return_run_details=true --jq '.workflow_run_id')
+          [[ "$run" =~ ^[1-9][0-9]*$ ]] || { echo "::error::Dispatch returned no run ID"; exit 1; }
           gh run watch "$run" --repo "$GITHUB_REPOSITORY" --exit-status

.github/workflows/promote.yml

@@ -1,12 +1,7 @@
-# Moves an environment to a release by writing its channel on `deploy-state`, which the hosts poll.
-#
-# The hosts pin this workflow's identity, and a GitHub environment gates it, so a signature carrying
-# that identity is proof its reviewers approved. That holds only while this workflow stays
-# non-reusable: a `workflow_call` trigger would let any caller mint the same identity. The release
-# reaches staging by dispatching this workflow, not by triggering on its completion, so no run here
-# inherits a context it did not ask for.
+# Hosts trust this workflow's signing identity. Keep signing behind the environment gate;
+# making this workflow reusable would let callers share that identity.
 name: Promote
-run-name: Promote ${{ inputs.release }} to ${{ inputs.environment }}
+run-name: Promote ${{ inputs.release || inputs.commit }} to ${{ inputs.environment }}
 
 on:
   workflow_dispatch:
@@ -24,6 +19,10 @@ on:
         description: Commit to run, as a full SHA. Only for an environment that follows main.
         type: string
         required: false
+      automatic:
+        description: Follow main only if the channel is not frozen or ahead of this build
+        type: boolean
+        default: false
       allow-rollback:
         description: Permit moving this environment backwards
         type: boolean
@@ -39,22 +38,49 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  automatic:
+    if: ${{ inputs.automatic }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      apply: ${{ steps.policy.outputs.apply }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: deploy-state
+          path: deploy-state
+          persist-credentials: false
+      - uses: ./.github/actions/setup-toolchain
+        with:
+          install: "none"
+      # The workflow lock covers this read through publication, including manually requested holds.
+      - name: Check automatic promotion
+        id: policy
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMIT: ${{ inputs.commit }}
+          CHANNEL: ${{ inputs.environment }}
+        run: node scripts/automatic-promotion.ts
+
   promote:
+    needs: automatic
+    if: ${{ !cancelled() && !failure() && (!inputs.automatic || needs.automatic.outputs.apply == 'true') }}
     runs-on: ubuntu-latest
     timeout-minutes: 20
     environment:
       name: ${{ inputs.environment }}
-      # GitHub records this as the deployment's environment_url, on the status it writes when the
-      # job ends. A status posted from inside the job would be superseded by that one, so the URL
-      # has to come from here rather than from a step. It is a step output because APP_HOSTNAME is
-      # scoped to the environment being resolved.
+      # APP_HOSTNAME is environment-scoped, so resolve it after the job starts.
       url: ${{ steps.release.outputs.environment_url }}
     permissions:
       contents: write
       id-token: write
     steps:
-      # `deploy-state` carries channels and no code, so the tooling that writes it is checked out
-      # from the ref this workflow was dispatched on and the branch itself sits beside it.
+      # Tooling comes from the dispatched workflow ref, not from the deployment target.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
@@ -71,17 +97,7 @@ jobs:
 
       - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
-      # The resolver is tooling: it comes from the default branch so that a commit older than it can
-      # still be promoted, which is exactly what rolling an environment back means.
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          path: .promotion-scripts
-          sparse-checkout: scripts
-          persist-credentials: false
-
-      # The pins are data about the commit being promoted, so they come from that commit. Reading
-      # them from the default branch instead would deploy one commit's code against another's
-      # upstream images.
+      # Unlike tooling, upstream image pins must come from the deployment target.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         if: ${{ inputs.commit != '' }}
         with:
@@ -106,8 +122,7 @@ jobs:
               echo "::error::Name a release or a commit, not both"; exit 1; }
             [[ "$COMMIT" =~ ^[0-9a-f]{40}$ ]] || {
               echo "::error::Follow a full commit SHA, not '$COMMIT'"; exit 1; }
-            # Only what is already on the default branch may be followed: a commit that is not an
-            # ancestor of main has not been through review, whoever is able to dispatch this.
+            # Dispatch permission must not authorize commits outside main.
             gh api "repos/$GITHUB_REPOSITORY/compare/$COMMIT...main" --jq .status |
               grep -qE '^(identical|ahead)$' || {
                 echo "::error::$COMMIT is not on the default branch"; exit 1; }
@@ -120,9 +135,7 @@ jobs:
           release="$REQUESTED"
           [[ "$release" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] || {
             echo "::error::Promote an immutable vX.Y.Z release, not '$release'"; exit 1; }
-          # GitHub tag immutability is not a gate here: the host takes the source commit and every
-          # image digest from the cosign-signed release lock, so a moved tag changes nothing that is
-          # deployed. Requiring it would refuse the older releases a rollback exists to reach.
+          # The host binds the tag's source tree to the signed release lock before applying it.
           [ "$(gh release view "$release" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft)" = false ] || {
             echo "::error::$release is still a draft"; exit 1; }
           echo "release=$release" >> "$GITHUB_OUTPUT"
@@ -144,10 +157,8 @@ jobs:
           channel=$(echo "$CHANNEL" | tr '[:upper:]' '[:lower:]')
           mkdir -p channels
           if [ "$FOLLOWS" = commit ]; then
-            # A commit has no release to fetch a lock from, so the channel carries the digests
-            # itself. They are covered by the signature below, which is the same authority that
-            # stands behind a release lock.
-            node "$GITHUB_WORKSPACE/.promotion-scripts/scripts/commit-image-lock.ts" \
+            # Commit deployments carry verified image digests in the signed channel.
+            node "$GITHUB_WORKSPACE/scripts/commit-image-lock.ts" \
               "$RELEASE" "$OWNER" "$GITHUB_WORKSPACE/.promotion-inventory/security/release-images.json" \
               > images.json
             jq -n --arg commit "$RELEASE" --slurpfile images images.json \
@@ -172,8 +183,6 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           RELEASE: ${{ steps.release.outputs.release }}
         run: |
-          # An empty commit would read as a move forward to hosts that compare ancestry, so a channel
-          # already at this release produces none.
           node ../scripts/commit-via-api.ts \
             --branch deploy-state \
             --message "chore(deploy): ${CHANNEL_FILE} -> ${RELEASE}" \
@@ -186,8 +195,7 @@ jobs:
           HOSTNAME: ${{ vars.APP_HOSTNAME }}
         run: |
           set -euo pipefail
-          # Nothing here can push the hosts, so the deploy is observed: the webapp publishes the
-          # version it runs, which makes convergence visible without any access to the host.
+          # Observe the public webapp version; host metrics report stack readiness separately.
           deadline=$(( SECONDS + 900 ))
           while [ "$SECONDS" -lt "$deadline" ]; do
             config=$(curl -fsS --max-time 20 "https://${HOSTNAME}/" |

.github/workflows/review-policy.yml

@@ -1,29 +1,19 @@
 name: Review policy
 
 on:
-  pull_request_target: # zizmor: ignore[dangerous-triggers] API reads only; no pull-request code is executed.
+  pull_request_target: # zizmor: ignore[dangerous-triggers] Trusted policy only; no pull-request code is executed.
     types: [opened, reopened, synchronize, ready_for_review, edited]
 
 permissions: {}
 
 concurrency:
-  # Never cancel: runs in a group are serialised, so the newest event's decision is the one that
-  # lands, and a cancelled run leaves an approval unsubmitted rather than half-written.
+  # Serialize writes without interrupting an approval; each run re-reads the current head.
   group: review-policy-${{ github.event.pull_request.number }}
   cancel-in-progress: false
 
 jobs:
-  # This job is *not* a required status check, and must never become one. The `main` ruleset requires
-  # one native approving review; all this job does is supply that approval for the authors listed in
-  # `REVIEW_POLICY_MAINTAINERS`. A pull request by anyone else gets no approval here and sits in
-  # GitHub's own "Review required" state, which blocks merging, merge-queue entry and auto-merge.
-  #
-  # `synchronize` is load-bearing: the ruleset dismisses stale approvals on push, so every push has
-  # to earn a fresh one. `edited` is load-bearing for stacked pull requests: merging a lower layer
-  # retargets the upper one onto `main`, which fires no other event here — without it the layer
-  # arrives at the queue unapproved and cannot enter. For the same reason there is no `branches:`
-  # filter: a layer must already hold its approval when it is retargeted, and an approval on a pull
-  # request targeting anything but `main` satisfies no rule and is inert.
+  # Not a required check: GitHub's native review requirement owns merge eligibility.
+  # No base filter: stacked layers need approval before retargeting. Pushes dismiss stale reviews.
   approve:
     name: Approve a maintainer's pull request
     runs-on: ubuntu-latest
@@ -32,18 +22,15 @@ jobs:
       contents: read
       pull-requests: write
     steps:
-      # The default branch, never `github.sha` or the pull request's head: the base branch's copy of
-      # the policy is the authoritative one, and nothing from the pull request is fetched or run.
+      # Execute only the default branch's policy, never the pull request's code.
       - name: Load the trusted policy evaluator
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.repository.default_branch }}
           persist-credentials: false
           sparse-checkout: scripts
 
-      # The review is attributed to `github-actions[bot]`, which counts toward the ruleset's
-      # `required_approving_review_count`. That needs the organisation's "Allow GitHub Actions to
-      # create and approve pull requests" setting left on.
+      # Requires the organisation's "Allow GitHub Actions to create and approve pull requests" setting.
       - name: Approve when the author is a listed maintainer
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env: