fix(release): hand off successful Main Guard proof (#10677)

chubes4 · web-flow · commit 97b1d81111b2 · 2026-07-28T19:39:52.000-04:00
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,7 +1,7 @@
 # Continuous release pipeline for Homeboy.
 #
-# Triggers on push to main (and manual dispatch). Checks for releasable
-# conventional commits since the last tag. If found:
+# Triggers after Main Guard validates main (or by manual dispatch). Checks for
+# releasable conventional commits since the last tag. If found:
 #   1. Quality gate (audit, lint, test)
 #   2. Version bump + changelog generation from conventional commits
 #   3. Cross-platform binary builds via cargo-dist
@@ -20,7 +20,9 @@ permissions:
   pull-requests: write
 
 on:
-  push:
+  workflow_run:
+    workflows: [Main Guard]
+    types: [completed]
     branches: [main]
   workflow_dispatch:
     inputs:
@@ -41,11 +43,12 @@ env:
   RELEASE_BLOCKING_COMMANDS: ${{ inputs.release_blocking_commands || 'review lint,review test' }}
   HOMEBOY_NO_UPDATE_CHECK: '1'
   RELEASE_MIN_FREE_KB: '5242880'
+  RELEASE_CANDIDATE_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
 
-# Only one release pipeline at a time. If a push arrives while a release
-# is already running, it queues (never cancels). The queued run starts
-# after the first finishes and its check job exits in seconds because
-# HEAD is already tagged — zero wasted work.
+# Only one release pipeline at a time. If Main Guard validates another SHA
+# while a release is already running, it queues (never cancels). The queued run
+# starts after the first finishes and its check job exits in seconds if the
+# candidate is already tagged.
 concurrency:
   group: release-${{ inputs.release_tag || github.ref }}
   cancel-in-progress: false
@@ -55,6 +58,7 @@ jobs:
   # Fast exit if nothing to release (e.g. chore-only commits).
   check:
     name: Check for releasable commits
+    if: github.event_name == 'workflow_dispatch' || (github.event.workflow_run.event == 'push' && github.event.workflow_run.conclusion == 'success')
     runs-on: ubuntu-latest
     outputs:
       should-release: ${{ steps.check.outputs.should-release }}
@@ -66,7 +70,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ inputs.release_tag || github.ref }}
+          ref: ${{ inputs.release_tag || env.RELEASE_CANDIDATE_SHA }}
           fetch-depth: 0
 
       - name: Restore failed release marker
@@ -75,7 +79,7 @@ jobs:
         uses: actions/cache/restore@v4
         with:
           path: ${{ runner.temp }}/homeboy-release-last-failed
-          key: release-last-failed-${{ github.ref_name }}-${{ github.sha }}
+          key: release-last-failed-${{ github.ref_name }}-${{ env.RELEASE_CANDIDATE_SHA }}
           restore-keys: |
             release-last-failed-${{ github.ref_name }}-
 
@@ -196,8 +200,8 @@ jobs:
             echo "::notice::Release recovery will publish ${RECOVERY_TAG}"
           elif [ -n "${STRANDED_TAG}" ]; then
             # Recovery PREEMPTS a fresh release, and preempts the failed-SHA
-            # marker too. The marker is keyed to github.sha and only means
-            # "do not re-prepare this HEAD"; finishing an already-prepared tag
+            # marker too. The marker is keyed to the release candidate SHA and
+            # only means "do not re-prepare this HEAD"; finishing an already-prepared tag
             # is a different, HEAD-independent action. Preemption is the whole
             # point: a fresh release prepared on top of a stranded tag buries
             # it under a newer published release, where the contiguous-window
@@ -231,31 +235,57 @@ jobs:
             echo "::notice::Release dry-run predicts v${RELEASE_VERSION} (${BUMP_TYPE})"
           fi
 
-  # ── Step 2: Exact-SHA release qualification ──
+  # ── Step 2: Exact-SHA release proof ──
   #
-  # A release owns an immutable candidate (github.sha), unlike Main Guard's
-  # push monitoring, which is intentionally latest-wins. Reuse terminal green
-  # Main Guard evidence for this SHA when it exists; otherwise dispatch a
-  # non-cancellable qualification and await that exact proof.
+  # Automatic releases are downstream of a successful Main Guard and consume
+  # that run's immutable SHA directly. Manual releases have no triggering proof,
+  # so they retain the explicit lookup/dispatch qualification path.
   release-qualification:
-    name: Release qualification
+    name: Bind release proof
     needs: check
     if: needs.check.outputs.should-release == 'true' && needs.check.outputs.recovery-release != 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 45
     outputs:
-      candidate-sha: ${{ steps.proof.outputs.candidate-sha }}
-      proof-sha: ${{ steps.proof.outputs.proof-sha }}
-      proof-run: ${{ steps.proof.outputs.proof-run }}
-      proof-status: ${{ steps.proof.outputs.proof-status }}
-      next-action: ${{ steps.proof.outputs.next-action }}
+      candidate-sha: ${{ steps.main_guard.outputs['candidate-sha'] || steps.proof.outputs['candidate-sha'] }}
+      proof-sha: ${{ steps.main_guard.outputs['proof-sha'] || steps.proof.outputs['proof-sha'] }}
+      proof-run: ${{ steps.main_guard.outputs['proof-run'] || steps.proof.outputs['proof-run'] }}
+      proof-status: ${{ steps.main_guard.outputs['proof-status'] || steps.proof.outputs['proof-status'] }}
+      next-action: ${{ steps.main_guard.outputs['next-action'] || steps.proof.outputs['next-action'] }}
     steps:
-      - name: Reuse or await exact Main Guard proof
+      - name: Consume triggering Main Guard proof
+        id: main_guard
+        if: github.event_name == 'workflow_run'
+        env:
+          CANDIDATE_SHA: ${{ github.event.workflow_run.head_sha }}
+          PROOF_RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}
+        run: |
+          {
+            echo "candidate-sha=${CANDIDATE_SHA}"
+            echo "proof-sha=${CANDIDATE_SHA}"
+            echo "proof-run=${PROOF_RUN}"
+            echo "proof-status=success"
+            echo "next-action=release immutable candidate"
+          } >> "$GITHUB_OUTPUT"
+
+          {
+            echo "### Release qualification"
+            echo
+            echo "- Selected SHA: \`${CANDIDATE_SHA}\`"
+            echo "- Exact gate proof SHA: \`${CANDIDATE_SHA}\`"
+            echo "- Exact gate proof run: ${PROOF_RUN}"
+            echo "- Proof status: \`success\`"
+            echo "- Next action: release immutable candidate"
+            echo "- Proof source: triggering Main Guard workflow"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Qualify manually selected candidate
         id: proof
+        if: github.event_name == 'workflow_dispatch'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}
-          CANDIDATE_SHA: ${{ github.sha }}
+          CANDIDATE_SHA: ${{ env.RELEASE_CANDIDATE_SHA }}
           DRY_RUN: ${{ inputs.dry-run || 'false' }}
         run: |
           set -euo pipefail
@@ -342,7 +372,7 @@ jobs:
         with:
           # Recovery checks out an older release tag downstream, but the
           # finalizer must include the current recovery contract from main.
-          ref: ${{ github.sha }}
+          ref: ${{ env.RELEASE_CANDIDATE_SHA }}
 
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
@@ -385,7 +415,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ inputs.release_tag || github.ref }}
+          ref: ${{ inputs.release_tag || env.RELEASE_CANDIDATE_SHA }}
           fetch-depth: 0
 
       - name: Download homeboy binary
@@ -433,7 +463,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ inputs.release_tag || github.ref }}
+          ref: ${{ inputs.release_tag || env.RELEASE_CANDIDATE_SHA }}
           fetch-depth: 0
 
       - name: Download homeboy binary
@@ -478,7 +508,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ inputs.release_tag || github.ref }}
+          ref: ${{ inputs.release_tag || env.RELEASE_CANDIDATE_SHA }}
           fetch-depth: 0
 
       - name: Download homeboy binary
@@ -540,7 +570,7 @@ jobs:
       - name: Checkout workflow event commit
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ env.RELEASE_CANDIDATE_SHA }}
 
       - name: Enforce release-blocking commands
         env:
@@ -581,12 +611,12 @@ jobs:
           app-id: ${{ secrets.HOMEBOY_APP_ID }}
           private-key: ${{ secrets.HOMEBOY_APP_PRIVATE_KEY }}
 
-      # A push-triggered self-recovery has no `inputs.release_tag`, and main has
+      # An automatic self-recovery has no `inputs.release_tag`, and main has
       # normally moved well past the stranded tag by now. Check out the tag
       # being recovered so every job in the publish chain agrees on the tree.
       - uses: actions/checkout@v4
         with:
-          ref: ${{ inputs.release_tag || (needs.check.outputs.recovery-release == 'true' && needs.check.outputs['release-tag']) || github.ref }}
+          ref: ${{ inputs.release_tag || (needs.check.outputs.recovery-release == 'true' && needs.check.outputs['release-tag']) || env.RELEASE_CANDIDATE_SHA }}
           fetch-depth: 0
           persist-credentials: true
           token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
@@ -1092,7 +1122,7 @@ jobs:
           RELEASE_TAG: ${{ needs.prepare.outputs['release-tag'] }}
           RELEASE_VERSION: ${{ needs.prepare.outputs['release-version'] }}
           EXPECTED_ASSETS: ${{ needs.plan.outputs.expected-assets }}
-          CONTROL_SHA: ${{ github.sha }}
+          CONTROL_SHA: ${{ env.RELEASE_CANDIDATE_SHA }}
         run: |
           set -euo pipefail
           mkdir -p draft-adoption
@@ -1156,7 +1186,7 @@ jobs:
         if: needs.prepare.outputs.recovery-release == 'true'
         env:
           RELEASE_TAG: ${{ needs.prepare.outputs['release-tag'] }}
-          CONTROL_SHA: ${{ github.sha }}
+          CONTROL_SHA: ${{ env.RELEASE_CANDIDATE_SHA }}
           ADOPTION_SOURCE: ${{ needs.prepare.outputs.recovery-release == 'true' && 'draft-adoption' || 'artifacts' }}
           ARTIFACT_ORIGIN: ${{ needs.plan.outputs.draft-complete == 'true' && 'pre-existing draft assets (rebuild skipped)' || 'rebuilt and re-uploaded by this run' }}
         run: |
@@ -1257,6 +1287,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          ref: ${{ env.RELEASE_CANDIDATE_SHA }}
           persist-credentials: false
           submodules: recursive
 
@@ -1276,10 +1307,12 @@ jobs:
       - host
       - verify-published
       - announce
-    if: ${{ always() && github.event_name == 'push' && needs.check.outputs.should-release == 'true' && contains(toJson(needs), '"result":"failure"') }}
+    if: ${{ always() && github.event_name == 'workflow_run' && needs.check.outputs.should-release == 'true' && contains(toJson(needs), '"result":"failure"') }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.RELEASE_CANDIDATE_SHA }}
 
       # The SHA marker means "do not re-PREPARE this HEAD". A recovery run
       # never prepares anything — it finishes an already-prepared tag — so
@@ -1294,12 +1327,12 @@ jobs:
         uses: actions/cache/save@v4
         with:
           path: ${{ runner.temp }}/homeboy-release-last-failed
-          key: release-last-failed-${{ github.ref_name }}-${{ github.sha }}
+          key: release-last-failed-${{ github.ref_name }}-${{ env.RELEASE_CANDIDATE_SHA }}
 
       # A failed recovery is charged to the TAG, so a stranded tag that cannot
-      # be published gets a bounded retry budget instead of re-firing on every
-      # push forever. `detect-stranded-release.sh` refuses a tag once it hits
-      # MAX_RECOVERY_ATTEMPTS and falls through to a normal fresh release.
+      # be published gets a bounded retry budget instead of re-firing after
+      # every successful Main Guard. `detect-stranded-release.sh` refuses a tag
+      # once it hits MAX_RECOVERY_ATTEMPTS and falls through to a fresh release.
       - name: Restore recovery attempts
         if: needs.check.outputs.recovery-release == 'true' && needs.check.outputs['release-tag'] != ''
         uses: actions/cache/restore@v4
@@ -1347,7 +1380,7 @@ jobs:
       - host
       - verify-published
       - announce
-    if: ${{ always() && github.event_name == 'push' && needs.check.outputs.should-release == 'true' && !contains(toJson(needs), '"result":"failure"') && !contains(toJson(needs), '"result":"cancelled"') }}
+    if: ${{ always() && github.event_name == 'workflow_run' && needs.check.outputs.should-release == 'true' && !contains(toJson(needs), '"result":"failure"') && !contains(toJson(needs), '"result":"cancelled"') }}
     runs-on: ubuntu-latest
     steps:
       - name: Clear failed SHA cache
diff --git a/tests/release_expected_assets_test.rs b/tests/release_expected_assets_test.rs
@@ -179,11 +179,11 @@ fn the_plan_job_still_fails_closed_when_cargo_dist_plans_no_artifacts() {
 fn recovery_records_control_binary_and_release_target_provenance_separately() {
     // Issue #10519: recovery used to execute the stranded tag's own binary, so
     // a publisher fix merged after the tag could never repair it. The control
-    // binary now comes from `gate-build` at `github.sha` while the release
+    // binary now comes from `gate-build` at the proven candidate while the release
     // target stays pinned to the tag; the run has to state both.
     let workflow = release_workflow();
     assert!(
-        workflow.contains("CONTROL_SHA: ${{ github.sha }}"),
+        workflow.contains("CONTROL_SHA: ${{ env.RELEASE_CANDIDATE_SHA }}"),
         "the finalizer must record which commit built the control binary"
     );
     assert!(workflow.contains("| control binary | "));
diff --git a/tests/release_workflow_test.rs b/tests/release_workflow_test.rs
@@ -156,8 +156,8 @@ fn release_quality_policy_checks_out_event_commit_before_running_script() {
     );
 
     assert!(
-        policy.contains("ref: ${{ github.sha }}"),
-        "release-quality-policy must check out the exact workflow/event commit (github.sha)"
+        policy.contains("ref: ${{ env.RELEASE_CANDIDATE_SHA }}"),
+        "release-quality-policy must check out the proven release candidate"
     );
 }
 
@@ -214,22 +214,48 @@ fn release_concurrency_scopes_recovery_runs_to_the_requested_tag() {
 }
 
 #[test]
-fn release_reuses_or_awaits_an_exact_main_guard_qualification() {
+fn automatic_release_consumes_the_triggering_main_guard_without_polling() {
     let workflow = release_workflow();
     let qualification = job_section(workflow, "release-qualification");
+    let proof = release_step_block(qualification, "name: Consume triggering Main Guard proof");
+    let check = job_section(workflow, "check");
 
-    assert!(qualification.contains("CANDIDATE_SHA: ${{ github.sha }}"));
-    assert!(qualification.contains("GH_REPO: ${{ github.repository }}"));
-    assert!(qualification.contains("gh run list --workflow audit-debt.yml"));
-    assert!(qualification.contains("--commit \"$CANDIDATE_SHA\""));
-    assert!(qualification.contains(
+    assert!(workflow.contains(
+        "workflow_run:\n    workflows: [Main Guard]\n    types: [completed]\n    branches: [main]"
+    ));
+    assert!(!workflow.contains("push:\n    branches: [main]"));
+    assert!(workflow.contains(
+        "RELEASE_CANDIDATE_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}"
+    ));
+    assert!(check.contains("github.event.workflow_run.event == 'push'"));
+    assert!(check.contains("github.event.workflow_run.conclusion == 'success'"));
+    assert!(proof.contains("CANDIDATE_SHA: ${{ github.event.workflow_run.head_sha }}"));
+    assert!(proof.contains("github.event.workflow_run.id"));
+    assert!(proof.contains("proof-status=success"));
+    assert!(!proof.contains("gh run list"));
+    assert!(!proof.contains("gh workflow run"));
+    assert!(!proof.contains("sleep 30"));
+}
+
+#[test]
+fn manual_release_reuses_or_awaits_an_exact_main_guard_qualification() {
+    let workflow = release_workflow();
+    let qualification = job_section(workflow, "release-qualification");
+    let proof = release_step_block(qualification, "name: Qualify manually selected candidate");
+
+    assert!(proof.contains("if: github.event_name == 'workflow_dispatch'"));
+    assert!(proof.contains("CANDIDATE_SHA: ${{ env.RELEASE_CANDIDATE_SHA }}"));
+    assert!(proof.contains("GH_REPO: ${{ github.repository }}"));
+    assert!(proof.contains("gh run list --workflow audit-debt.yml"));
+    assert!(proof.contains("--commit \"$CANDIDATE_SHA\""));
+    assert!(proof.contains(
         "gh workflow run audit-debt.yml --ref main -f qualification_sha=\"$CANDIDATE_SHA\""
     ));
-    assert!(qualification.contains("proof-status=${conclusion}"));
-    assert!(qualification.contains("Selected SHA:"));
-    assert!(qualification.contains("Exact gate proof run:"));
-    assert!(qualification.contains("Proof source: ${action}"));
-    assert!(qualification.contains("Dry run: release mutation remains disabled"));
+    assert!(proof.contains("proof-status=${conclusion}"));
+    assert!(proof.contains("Selected SHA:"));
+    assert!(proof.contains("Exact gate proof run:"));
+    assert!(proof.contains("Proof source: ${action}"));
+    assert!(proof.contains("Dry run: release mutation remains disabled"));
 }
 
 #[test]
@@ -893,16 +919,16 @@ fn release_fast_path_keeps_every_publication_verification() {
     );
 
     // The control binary that performs adoption is still the one built from the
-    // dispatching commit, not from the stranded tag (#10519's headline defect,
+    // proven candidate, not from the stranded tag (#10519's headline defect,
     // fixed in #10560 — keep it fixed).
     let host = job_section(workflow, "host");
     assert!(
         host.contains("binary-path: ${{ needs.prepare.outputs.recovery-release == 'true' && '.homeboy-bin/homeboy' || '' }}"),
         "recovery must execute the freshly built control binary, never the stranded tag's"
     );
     assert!(
-        job_section(workflow, "gate-build").contains("ref: ${{ github.sha }}"),
-        "the control binary must be built from the dispatching commit"
+        job_section(workflow, "gate-build").contains("ref: ${{ env.RELEASE_CANDIDATE_SHA }}"),
+        "the control binary must be built from the proven release candidate"
     );
     assert!(
         host.contains("ref: ${{ needs.prepare.outputs['release-tag'] }}"),
@@ -916,7 +942,7 @@ fn release_fast_path_keeps_every_publication_verification() {
 
 /// Recovery is allowed — required — to run a control binary NEWER than the tag
 /// it repairs; that is the bootstrap #10519 asks for, and #10560 built it by
-/// pinning `gate-build` to `github.sha`. The inverse was never bounded: a
+/// pinning `gate-build` to the release candidate SHA. The inverse was never bounded: a
 /// control binary from a tree that never contained the tag cannot be shown to
 /// carry the publisher fix recovery exists to apply, and would impose a release
 /// contract the tag was never planned under.
@@ -931,7 +957,7 @@ fn release_recovery_records_control_binary_lineage_against_the_release_target()
     let adoption = release_step_block(host, "name: Create remote draft adoption manifest");
 
     assert!(
-        adoption.contains("CONTROL_SHA: ${{ github.sha }}"),
+        adoption.contains("CONTROL_SHA: ${{ env.RELEASE_CANDIDATE_SHA }}"),
         "the adoption manifest must record which commit the control binary was built from"
     );
     assert!(
