fix(ci): validate the Version PR and preflight its release evidence

The changesets action pushes the Version PR with GITHUB_TOKEN, and a push
made with that token starts no workflow run. The conclusion drawn from
that was that the Version PR cannot be checked at all, so it merged
through a standing ruleset bypass. workflow_dispatch is one of the two
documented exceptions to the no-new-run rule, so the same token starts
the same CI/CD workflow on the Version PR's own branch — no app, no
personal access token, no long-lived credential. Every Version PR head
commit gets one run, decided by asking whether the head already has one,
so a missed dispatch heals on the next push to main.

That run also carries a release evidence preflight. #1743 pinned subject
parity — the pre-release scans cover the images the release covers — but
the vulnerability policy is only one of the things the release gate
evaluates, and a release was still the only thing that ever produced an
evidence bundle. SBOM triple validation, the licence report binding,
index membership, and the linux/arm64 vulnerability policy for the images
we build could each fail for the first time at a release; the pinned
upstream digests need no build, so #1743 already covers both of their
platforms on the pull request that changes them. The preflight generates
and verifies a real bundle over the images its own run built, through the
one generator and the one verifier the release uses, so the only checks a
release can be the first to perform are the signature checks that need
signing material a release creates.

Evidence generation and image-digest resolution move out of release.yml
into scripts/generate-release-evidence.ts and
scripts/resolve-release-images.ts so there is one of each rather than a
second copy the preflight could drift from. Platform resolution reuses
isImageIndex, so a release subject that is a single manifest fails rather
than falling back to the index digest. ci-contract.test.ts asserts both
callers run both scripts and that the verifier's only mode-conditional
behaviour is signature verification, so a check gated on anything else
fails the contract test rather than a release; release-management.mdx
carries the check-by-check table and why the upstream images are
deliberately judged twice on the Version PR.

Verified with pnpm run format and pnpm run check, and with the new
node:test coverage for the resolver's retry and hand-off, the
generator's manifest against the real verifier, and the dispatcher's
branch and run decisions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: FelixTJDietrich

.github/workflows/cicd.yml

@@ -2,15 +2,24 @@ name: CI/CD
 
 on:
   workflow_dispatch:
+    inputs:
+      release-preflight:
+        description: "Generate and verify this ref's release evidence bundle, everything the release gate checks except the signatures that only exist at a release"
+        type: boolean
+        default: false
   push:
     branches: ["main"]
   pull_request:
     branches: ["**"]
   merge_group:
 
+# A dispatch never shares a group with a push on the same ref: the Version PR is validated by
+# dispatch while `main` is validated by push, and a push produces the images a release promotes, so
+# it is the one run that must never be cancelled by another. A pull request or a dispatch validates
+# a branch that is still moving, where the newest run is the only one whose answer is wanted.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' }}
 
 permissions: {}
 
@@ -40,6 +49,7 @@ jobs:
       docker-config: ${{ steps.filter.outputs.docker-config }}
       pmd-canary: ${{ steps.filter.outputs.pmd-canary }}
       version-bump: ${{ steps.version_bump.outputs.changed }}
+      version: ${{ steps.version.outputs.version }}
       any-code: ${{ steps.filter.outputs.webapp == 'true' || steps.filter.outputs.application-server == 'true' || steps.filter.outputs.tooling == 'true' || steps.filter.outputs.agent-images == 'true' || steps.filter.outputs.postgres-image == 'true' }}
       should_skip: ${{ steps.skip_check.outputs.should_skip }}
     timeout-minutes: 5
@@ -54,6 +64,12 @@ jobs:
         with:
           do_not_skip: '["workflow_dispatch", "push", "merge_group"]'
 
+      # The version this ref carries, which the release evidence preflight needs to resolve the
+      # namespace and signing identity a release of it would use.
+      - name: Read the release version
+        id: version
+        run: echo "version=$(jq -r .version package.json)" >> "$GITHUB_OUTPUT"
+
       - name: Detect version bump
         id: version_bump
         if: github.event_name == 'push'
@@ -412,14 +428,82 @@ jobs:
       agent_images_changed: ${{ (needs.detect-changes.outputs.agent-images == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
       postgres_image_changed: ${{ (needs.detect-changes.outputs.postgres-image == 'true' || needs.detect-changes.outputs.docker-config == 'true' || github.event_name != 'pull_request') && 'true' || 'false' }}
 
+  # Everything the release evidence gate checks, against the images this run just built, except the
+  # signatures and attestations that do not exist until a release creates them. A release was the
+  # first and only thing that ever produced an evidence bundle, so the SBOM triple, the licence
+  # report binding, index membership, and the linux/arm64 vulnerability policy for the images we
+  # build could each fail for the first time at the release — the pinned upstream digests need no
+  # build, so ci-security-scan.yml already covers both of their platforms on the pull request that
+  # changes them. release-management.mdx § Nothing may fail for the first time at a release carries
+  # the check-by-check reasoning.
+  Release-preflight:
+    name: "Release evidence preflight"
+    needs: [detect-changes, Build, Docker]
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.release-preflight }}
+    timeout-minutes: 45
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-node-pnpm
+        with:
+          install: "none"
+
+      - uses: ./.github/actions/setup-release-security-tools
+
+      # The same freshness bound the release applies: a stale mirror must not be read as a clean scan.
+      - uses: ./.github/actions/download-trivy-db
+        with:
+          max-age-hours: "24"
+
+      - uses: ./.github/actions/ghcr-login
+        with:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate and verify this ref's release evidence
+        env:
+          # The version this ref would release under. On the Version PR branch that is the release
+          # being prepared; on any other ref it is the version already published, and either way it
+          # resolves the namespace and identity the evidence gate demands.
+          RELEASE: v${{ needs.detect-changes.outputs.version }}
+          SOURCE_TAG: run-${{ github.run_id }}-${{ github.run_attempt }}
+          TRIVY_USERNAME: ${{ github.actor }}
+          TRIVY_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          node scripts/resolve-release-images.ts "$SOURCE_TAG" release-images.tsv
+          node scripts/generate-release-evidence.ts evidence \
+            --release "$RELEASE" --commit "$GITHUB_SHA" --digests release-images.tsv
+          node scripts/verify-release-evidence.ts evidence --write-validation
+          # Again without --write-validation, which re-derives the validation documents and fails if
+          # they changed: the release runs the verifier twice for the same reason.
+          node scripts/verify-release-evidence.ts evidence
+
+      # An exit status cannot say which subject carries which finding.
+      - name: Upload the evidence bundle
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-evidence-preflight
+          path: evidence
+          if-no-files-found: warn
+          retention-days: 7
+
   all-ci-passed:
     name: "CI Status Gate"
     timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
       actions: read
       statuses: write
-    needs: [detect-changes, workflow-lint, zizmor, Quality, Build, Security, Test, Changesets, Compose, Docker]
+    needs: [detect-changes, workflow-lint, zizmor, Quality, Build, Security, Test, Changesets, Compose, Docker, Release-preflight]
     if: always()
     steps:
       - name: Generate workflow timeline
@@ -479,6 +563,7 @@ jobs:
           echo "Changesets:     ${{ needs.Changesets.result }}"
           echo "Compose:        ${{ needs.Compose.result }}"
           echo "Docker:         ${{ needs.Docker.result }}"
+          echo "Preflight:      ${{ needs.Release-preflight.result }}"
 
           if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
             echo "status=failure" >> $GITHUB_OUTPUT
@@ -531,6 +616,7 @@ jobs:
           echo "| Compose | $(result_to_emoji '${{ needs.Compose.result }}') |" >> $GITHUB_STEP_SUMMARY
           echo "| Security | $(result_to_emoji '${{ needs.Security.result }}') |" >> $GITHUB_STEP_SUMMARY
           echo "| Docker | $(result_to_emoji '${{ needs.Docker.result }}') |" >> $GITHUB_STEP_SUMMARY
+          echo "| Release evidence preflight | $(result_to_emoji '${{ needs.Release-preflight.result }}') |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
 
           echo "### 📁 Components Changed" >> $GITHUB_STEP_SUMMARY

.github/workflows/release.yml

@@ -105,50 +105,17 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - uses: ./.github/actions/setup-node-pnpm
+        with:
+          install: "none"
+
+      # The images this release promotes, resolved through the same script the pre-merge evidence
+      # preflight resolves them with, so the two can never disagree about which artefact is subject.
       - name: Capture release image digests
         id: retag
         env:
           SOURCE_TAG: run-${{ github.event.workflow_run.id }}-${{ github.event.workflow_run.run_attempt }}
-        run: |
-          set -euo pipefail
-
-          mapfile -t IMAGES < <(jq -er '.images[]' security/release-images.json)
-          [ "${#IMAGES[@]}" -gt 0 ] || { echo "::error::Release image inventory is empty"; exit 1; }
-          declare -A DIGESTS=()
-          : > release-images.tsv
-
-          # Resolve the complete image inventory before generating evidence.
-          for img in "${IMAGES[@]}"; do
-            FULL_IMAGE="ghcr.io/hephaestus-build/$img"
-            for i in $(seq 1 24); do
-              digest=$(docker buildx imagetools inspect "$FULL_IMAGE:$SOURCE_TAG" --format '{{json .Manifest}}' 2>/dev/null | jq -er '.digest' 2>/dev/null) || true
-              if [[ "$digest" =~ ^sha256:[a-f0-9]{64}$ ]]; then
-                DIGESTS[$img]=$digest
-                break
-              fi
-              if [ "$i" -ge 24 ]; then
-                echo "::error::Could not resolve a valid digest for $FULL_IMAGE:$SOURCE_TAG after 120 s"
-                exit 1
-              fi
-              sleep 5
-            done
-          done
-
-          for img in "${IMAGES[@]}"; do
-            FULL_IMAGE="ghcr.io/hephaestus-build/$img"
-            echo "::group::$img"
-
-            SRC_DIGEST=${DIGESTS[$img]}
-            echo "$img source digest: $SRC_DIGEST"
-            printf '%s\t%s\n' "$img" "$SRC_DIGEST" >> release-images.tsv
-
-            case "$img" in
-              agent-pi)            echo "agent-pi-digest=$SRC_DIGEST" >> "$GITHUB_OUTPUT" ;;
-              application-server)  echo "application-server-digest=$SRC_DIGEST" >> "$GITHUB_OUTPUT" ;;
-              postgres)            echo "postgres-digest=$SRC_DIGEST" >> "$GITHUB_OUTPUT" ;;
-            esac
-            echo "::endgroup::"
-          done
+        run: node scripts/resolve-release-images.ts "$SOURCE_TAG" release-images.tsv
 
       - name: Verify Node-only agent-pi sandbox
         env:
@@ -171,10 +138,6 @@ jobs:
 
       - uses: ./.github/actions/setup-release-security-tools
 
-      - uses: ./.github/actions/setup-node-pnpm
-        with:
-          install: "none"
-
       # The database the whole evidence bundle is scanned against: recorded into the bundle, and
       # refused if it is over a day old, so a stale mirror cannot be signed as a fresh scan.
       - uses: ./.github/actions/download-trivy-db
@@ -186,61 +149,12 @@ jobs:
         env:
           TRIVY_USERNAME: ${{ github.actor }}
           TRIVY_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE: ${{ needs.release.outputs.tag_name }}
+          COMMIT: ${{ needs.release.outputs.sha }}
         run: |
           set -euo pipefail
-          mkdir -p evidence
-          : > release-platforms.tsv
-          started=$SECONDS
-          jq -n --arg syft "$(syft version -o json | jq -r .version)" \
-            --arg trivy "$(trivy version --format json | jq -r .Version)" \
-            --arg cosign "$(cosign version --json | jq -r .gitVersion)" \
-            '{syft: $syft, trivy: $trivy, cosign: $cosign}' > evidence/tool-versions.json
-          generate_evidence() {
-            local image=$1 repository=$2 digest=$3 provenance=$4
-            local ref="$repository@$digest"
-            for platform in linux/amd64 linux/arm64; do
-              suffix=${platform//\//-}
-              architecture=${platform#*/}
-              platform_digest=$(docker buildx imagetools inspect "$ref" --raw | jq -er \
-                --arg architecture "$architecture" \
-                '.manifests[] | select(.platform.os == "linux" and .platform.architecture == $architecture) | .digest')
-              [[ "$platform_digest" =~ ^sha256:[a-f0-9]{64}$ ]] || { echo "::error::$image $platform digest is malformed"; exit 1; }
-              platform_ref="$repository@$platform_digest"
-              printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$image" "$platform" "$digest" "$platform_digest" "$repository" "$provenance" >> release-platforms.tsv
-              # Scan the registry artifact, never a daemon copy of it: a daemon pull
-              # re-serializes an OCI manifest as Docker schema 2, so the SBOM would
-              # record a locally computed manifestDigest instead of the released one.
-              # --platform makes Syft fail loudly if the digest is not this platform's.
-              syft --from registry "$platform_ref" --platform "$platform" --scope squashed \
-                -o "syft-json=evidence/$image-$suffix.syft.json" \
-                -o "spdx-json=evidence/$image-$suffix.spdx.json" \
-                -o "cyclonedx-json=evidence/$image-$suffix.cdx.json"
-              trivy image --skip-db-update --scanners vuln --format json --output "evidence/$image-$suffix.trivy.json" "$platform_ref"
-              trivy image --skip-db-update --scanners license --format json --output "evidence/$image-$suffix.license.json" "$platform_ref"
-            done
-          }
-          while IFS=$'\t' read -r image digest; do
-            generate_evidence "$image" "ghcr.io/hephaestus-build/$image" "$digest" first-party
-          done < release-images.tsv
-          jq -r '.upstream[] | [.name, .repository, .digest] | @tsv' security/release-images.json |
-          while IFS=$'\t' read -r image repository digest; do
-            generate_evidence "$image" "$repository" "$digest" upstream
-          done
-          duration=$((SECONDS - started))
-          jq -n \
-            --arg schemaVersion "1" \
-            --arg generatedAt "$(date -u +%FT%TZ)" \
-            --arg release "${{ needs.release.outputs.tag_name }}" \
-            --arg commit "${{ needs.release.outputs.sha }}" \
-            --argjson durationSeconds "$duration" \
-            --rawfile subjects release-platforms.tsv \
-            '{schemaVersion: ($schemaVersion | tonumber), release: $release, commit: $commit,
-              generatedAt: $generatedAt, durationSeconds: $durationSeconds,
-              subjects: ($subjects | split("\n") | map(select(length > 0) | split("\t") |
-                {image: .[0], platform: .[1], indexDigest: .[2], digest: .[3], repository: .[4], provenance: .[5]}))}' \
-            > evidence/manifest.json
-          cp security/vulnerability-policy.json evidence/vulnerability-policy.json
-          cp security/release-images.json evidence/release-images.json
+          node scripts/generate-release-evidence.ts evidence \
+            --release "$RELEASE" --commit "$COMMIT" --digests release-images.tsv
           node scripts/verify-release-evidence.ts evidence --write-validation
           jq -er '.subjects[] | select(.provenance == "first-party") | [.repository, .digest, .image, .platform] | @tsv' evidence/manifest.json |
           while IFS=$'\t' read -r repository digest image platform; do
@@ -279,7 +193,7 @@ jobs:
           ASSET: ${{ steps.pin.outputs.asset-path }}
         run: |
           set -euo pipefail
-          while IFS=$'\t' read -r image digest; do
+          while IFS=$'\t' read -r image _ digest; do
             printf '%s  %s\n' "${digest#sha256:}" "$image"
           done < release-images.tsv > subjects.sha256
           sha256sum "$ASSET" >> subjects.sha256

.github/workflows/version-pr.yml

@@ -1,8 +1,11 @@
 name: Version PR
 
 # Maintains the changesets Version PR; release.yml handles merged version bumps.
-# GITHUB_TOKEN-authored updates do not trigger CI, so release automation uses the
-# ruleset bypass. A release still requires successful main CI.
+#
+# The changesets action pushes with GITHUB_TOKEN, and a push made with that token starts no workflow
+# run — so the Version PR used to carry no checks at all and merged through a ruleset bypass.
+# workflow_dispatch is one of the two documented exceptions to that rule, so the same token starts
+# CI/CD on the Version PR's own branch instead; scripts/dispatch-version-pr-ci.ts has the reasoning.
 #
 # Contributor guide: docs/contributor/release-management.mdx
 
@@ -21,6 +24,7 @@ jobs:
     timeout-minutes: 15
     runs-on: ubuntu-latest
     permissions:
+      actions: write # dispatch CI/CD on the Version PR's branch
       contents: write
       pull-requests: write
     steps:
@@ -40,3 +44,10 @@ jobs:
           pr-title: "chore(release): version packages"
           commit-message: "chore(release): version packages"
           github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      # Every Version PR head commit gets a CI/CD run, so the commit whose merge cuts a release is
+      # validated before it lands rather than after.
+      - name: Run CI on the Version PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: node scripts/dispatch-version-pr-ci.ts