fix(release): await completed beta qualification

Git-on-my-level · Git-on-my-level · commit 2cd71bfe0c81 · 2026-07-21T01:38:48.000-04:00
Trigger automatic beta promotion only from a completed, trusted qualification run and require explicit Stable confirmation for every pointer mutation.

Tests: actionlint desktop_qualify_beta.yml desktop_promote_beta.yml desktop_promote_prod.yml; python3 .github/scripts/test_desktop_qualification_dispatch.py; python3 .github/scripts/test_stable_promotion_verifiers.py; python3 .github/scripts/test_check_release_process_guards.py; make preflight (blocked only by inherited c5 changelog false-positive).

Failure-Class: FC-split-mutation-authority
diff --git a/.github/checks-manifest.yaml b/.github/checks-manifest.yaml
@@ -36,7 +36,7 @@ checks:
     reason: "advisory desktop release evidence and drift report"
   - id: desktop-qualification-immutable-dispatch
     command: ["python3", ".github/scripts/test_desktop_qualification_dispatch.py"]
-    triggers: ["codemagic.yaml", ".github/workflows/desktop_qualify_beta.yml", ".github/scripts/test_desktop_qualification_dispatch.py", ".github/checks-manifest.yaml"]
+    triggers: ["codemagic.yaml", ".github/workflows/desktop_qualify_beta.yml", ".github/workflows/desktop_promote_beta.yml", ".github/scripts/test_desktop_qualification_dispatch.py", ".github/checks-manifest.yaml"]
     lanes: ["local", "ci"]
     reason: "candidate qualification must dispatch and rebuild at one immutable candidate tag SHA"
   - id: desktop-changelog-io-tests
@@ -372,12 +372,12 @@ checks:
     reason: "#10163 mutation-tests production-family mobile API routing"
   - id: stable-pointer-precondition-cli
     command: ["python3", ".github/scripts/check_stable_pointer_precondition.py", "--help"]
-    triggers: [".github/workflows/desktop_promote_prod.yml", ".github/scripts/check_stable_pointer_precondition.py", ".github/scripts/verify_stable_appcast.py", ".github/scripts/test_stable_promotion_verifiers.py", ".github/checks-manifest.yaml"]
+    triggers: [".github/workflows/desktop_promote_prod.yml", ".github/scripts/check_stable_pointer_precondition.py", ".github/scripts/require_stable_promotion_confirmation.py", ".github/scripts/verify_stable_appcast.py", ".github/scripts/test_stable_promotion_verifiers.py", ".github/checks-manifest.yaml"]
     lanes: ["local", "ci"]
     reason: "#10163 keeps Stable retry acknowledgement and appcast verification executable"
   - id: stable-pointer-precondition-fixtures
     command: ["python3", ".github/scripts/test_stable_promotion_verifiers.py"]
-    triggers: [".github/workflows/desktop_promote_prod.yml", ".github/scripts/check_stable_pointer_precondition.py", ".github/scripts/verify_stable_appcast.py", ".github/scripts/test_stable_promotion_verifiers.py", ".github/checks-manifest.yaml"]
+    triggers: [".github/workflows/desktop_promote_prod.yml", ".github/scripts/check_stable_pointer_precondition.py", ".github/scripts/require_stable_promotion_confirmation.py", ".github/scripts/verify_stable_appcast.py", ".github/scripts/test_stable_promotion_verifiers.py", ".github/checks-manifest.yaml"]
     lanes: ["local", "ci"]
     reason: "#10163 mutation-sensitive Stable retry and default-channel feed fixtures"
   - id: stable-static-publication-fixtures
diff --git a/.github/scripts/check-desktop-prod-promotion-policy.py b/.github/scripts/check-desktop-prod-promotion-policy.py
@@ -9,6 +9,9 @@
     "on:\n  workflow_dispatch:",
     "confirm:",
     "promote-stable",
+    "Require explicit Stable confirmation",
+    "require_stable_promotion_confirmation.py",
+    '--operation "$OPERATION" --confirm "$CONFIRM"',
     "operation:",
     "expected_current_release_id:",
     "expected_generation:",
@@ -57,6 +60,10 @@ def validate(text: str) -> list[str]:
             errors.append(f"stable pointer promotion must not contain backend deployment or bypass path: {forbidden}")
     if "\n  push:" in text or "\n  schedule:" in text or "\n  release:" in text:
         errors.append("stable pointer promotion must remain manual-only")
+    confirmation = text.find("Require explicit Stable confirmation")
+    for later_step in ("Checkout promotion controls", "Generate Omi Bot token", "Google Auth"):
+        if confirmation == -1 or confirmation > text.find(later_step):
+            errors.append(f"Stable confirmation must fail closed before {later_step}")
     order = [text.find(fragment) for fragment in ORDERED_STEPS]
     if -1 in order or order != sorted(order):
         errors.append("stable promotion must fetch and verify retained identity before pointer mutation, then bridge and verify")
diff --git a/.github/scripts/check-release-process-guards.py b/.github/scripts/check-release-process-guards.py
@@ -299,7 +299,6 @@ def check_desktop_qualification_runner() -> list[str]:
         "check-desktop-auto-beta-candidate.py",
         "--automatic",
         "--no-promote",
-        "desktop_promote_beta.yml",
         "actions/create-github-app-token@v3",
         "desktop-beta-qualification-${{ inputs.release_tag }}",
         "cancel-in-progress: false",
diff --git a/.github/scripts/require_stable_promotion_confirmation.py b/.github/scripts/require_stable_promotion_confirmation.py
@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Fail closed unless a Stable pointer mutation has explicit operator intent."""
+
+from __future__ import annotations
+
+import argparse
+
+
+CONFIRMATION = "promote-stable"
+OPERATIONS = {"promote", "repoint"}
+
+
+def validate(*, operation: str, confirm: str) -> None:
+    if operation not in OPERATIONS:
+        raise ValueError(f"unsupported Stable operation: {operation}")
+    if confirm != CONFIRMATION:
+        raise ValueError(f"confirm must be exactly: {CONFIRMATION}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--operation", required=True)
+    parser.add_argument("--confirm", required=True)
+    args = parser.parse_args()
+    try:
+        validate(operation=args.operation, confirm=args.confirm)
+    except ValueError as error:
+        parser.error(str(error))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/.github/scripts/test_desktop_qualification_dispatch.py b/.github/scripts/test_desktop_qualification_dispatch.py
@@ -11,11 +11,13 @@
 ROOT = Path(__file__).resolve().parents[2]
 CODEMAGIC = ROOT / "codemagic.yaml"
 QUALIFIER = ROOT / ".github/workflows/desktop_qualify_beta.yml"
+BETA_PROMOTION = ROOT / ".github/workflows/desktop_promote_beta.yml"
 
 
 def validate(root: Path) -> list[str]:
     codemagic = (root / "codemagic.yaml").read_text(encoding="utf-8")
     qualifier = (root / ".github/workflows/desktop_qualify_beta.yml").read_text(encoding="utf-8")
+    beta_promotion = (root / ".github/workflows/desktop_promote_beta.yml").read_text(encoding="utf-8")
     errors: list[str] = []
     dispatch = codemagic.split("gh workflow run desktop_qualify_beta.yml", 1)[1].split("then", 1)[0]
     if '--ref "$CM_TAG"' not in dispatch:
@@ -26,27 +28,110 @@ def validate(root: Path) -> list[str]:
         errors.append("qualification must not check out mutable main")
     if "CHECKOUT_SHA=$(git rev-parse HEAD)" not in qualifier or "EVENT_SHA: ${{ github.sha }}" not in qualifier:
         errors.append("candidate validation must compare the fetched candidate tag against the checked-out event SHA")
+    if "gh workflow run desktop_promote_beta.yml" in qualifier:
+        errors.append("qualification must not dispatch beta promotion before its run has completed")
+
+    for fragment, message in (
+        (
+            '  workflow_run:\n    workflows: ["Qualify Desktop Beta Candidate"]\n    types: [completed]',
+            "automatic beta promotion must be triggered only by completed qualification runs",
+        ),
+        (
+            "github.event.workflow_run.conclusion == 'success'",
+            "automatic beta promotion must require a successful qualification conclusion",
+        ),
+        (
+            "github.event.workflow_run.event == 'workflow_dispatch'",
+            "automatic beta promotion must require the trusted workflow_dispatch qualifier",
+        ),
+        (
+            "github.event.workflow_run.repository.full_name == github.repository",
+            "automatic beta promotion must require a same-repository workflow run",
+        ),
+        (
+            "github.event.workflow_run.head_repository.full_name == github.repository",
+            "automatic beta promotion must reject fork-sourced qualification",
+        ),
+        (
+            "github.event.workflow_run.path == '.github/workflows/desktop_qualify_beta.yml'",
+            "automatic beta promotion must require the desktop qualification workflow path",
+        ),
+        (
+            "RELEASE_TAG: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || inputs.release_tag }}",
+            "automatic beta promotion must derive its release tag from the completed qualifier",
+        ),
+        (
+            "QUALIFICATION_RUN_ID: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.id || inputs.qualification_run_id }}",
+            "automatic beta promotion must use the completed qualifier run ID",
+        ),
+        (
+            'test "$(jq -r .head_branch <<<"$run")" = "$RELEASE_TAG"',
+            "automatic beta promotion must bind qualification evidence to the release tag",
+        ),
+        (
+            'test "$(jq -r .head_sha <<<"$run")" = "$TARGET_SHA"',
+            "automatic beta promotion must bind qualification evidence to the exact tag SHA",
+        ),
+        (
+            'test "$QUALIFICATION_RUN_ID" = "$QUALIFIER_EVENT_RUN_ID"',
+            "automatic beta promotion must use the triggering completed qualification run",
+        ),
+        (
+            'test "$QUALIFIER_EVENT_HEAD_SHA" = "$TARGET_SHA"',
+            "automatic beta promotion must bind the triggering qualifier SHA to the release tag",
+        ),
+    ):
+        if fragment not in beta_promotion:
+            errors.append(message)
     return errors
 
 
 class DesktopQualificationDispatchTests(unittest.TestCase):
-    def test_current_configuration_uses_the_candidate_tag_and_event_sha(self) -> None:
+    def test_current_configuration_uses_the_candidate_tag_and_completed_qualifier(self) -> None:
         self.assertEqual(validate(ROOT), [])
 
     def test_mutations_drop_tag_ref_or_reintroduce_mutable_checkout(self) -> None:
         codemagic = CODEMAGIC.read_text(encoding="utf-8")
         qualifier = QUALIFIER.read_text(encoding="utf-8")
+        beta_promotion = BETA_PROMOTION.read_text(encoding="utf-8")
         mutations = (
-            (codemagic.replace('--ref "$CM_TAG" \\\n              ', "", 1), qualifier),
-            (codemagic, qualifier.replace("ref: ${{ github.sha }}", "ref: main", 1)),
-            (codemagic, qualifier.replace("CHECKOUT_SHA=$(git rev-parse HEAD)", "CHECKOUT_SHA=$(git rev-parse \"$RELEASE_TAG\")", 1)),
+            (codemagic.replace('--ref "$CM_TAG" \\\n              ', "", 1), qualifier, beta_promotion),
+            (codemagic, qualifier.replace("ref: ${{ github.sha }}", "ref: main", 1), beta_promotion),
+            (
+                codemagic,
+                qualifier.replace("CHECKOUT_SHA=$(git rev-parse HEAD)", "CHECKOUT_SHA=$(git rev-parse \"$RELEASE_TAG\")", 1),
+                beta_promotion,
+            ),
+            (codemagic, qualifier + '\n          gh workflow run desktop_promote_beta.yml\n', beta_promotion),
+            (
+                codemagic,
+                qualifier,
+                beta_promotion.replace("github.event.workflow_run.conclusion == 'success'", "github.event.workflow_run.conclusion == 'failure'", 1),
+            ),
+            (
+                codemagic,
+                qualifier,
+                beta_promotion.replace(
+                    "github.event.workflow_run.head_repository.full_name == github.repository",
+                    "github.event.workflow_run.head_repository.full_name == 'attacker/omi'",
+                    1,
+                ),
+            ),
+            (
+                codemagic,
+                qualifier,
+                beta_promotion.replace('test "$(jq -r .head_sha <<<"$run")" = "$TARGET_SHA"', 'test "$(jq -r .head_sha <<<"$run")" = main', 1),
+            ),
         )
-        for changed_codemagic, changed_qualifier in mutations:
+        for changed_codemagic, changed_qualifier, changed_beta_promotion in mutations:
             with self.subTest(mutation=changed_codemagic != codemagic), tempfile.TemporaryDirectory() as directory:
                 root = Path(directory)
                 (root / ".github/workflows").mkdir(parents=True)
                 (root / "codemagic.yaml").write_text(changed_codemagic, encoding="utf-8")
                 (root / ".github/workflows/desktop_qualify_beta.yml").write_text(changed_qualifier, encoding="utf-8")
+                (root / ".github/workflows/desktop_promote_beta.yml").write_text(
+                    changed_beta_promotion, encoding="utf-8"
+                )
                 self.assertTrue(validate(root))
 
 
diff --git a/.github/scripts/test_stable_promotion_verifiers.py b/.github/scripts/test_stable_promotion_verifiers.py
@@ -20,13 +20,37 @@ def _load(name: str):
 
 APPCAST = _load("verify_stable_appcast.py")
 POINTER = _load("check_stable_pointer_precondition.py")
+CONFIRMATION = _load("require_stable_promotion_confirmation.py")
+POLICY = _load("check-desktop-prod-promotion-policy.py")
 
 
 def _fields(release_id: str, generation: int) -> dict:
     return {"release_id": {"stringValue": release_id}, "generation": {"integerValue": str(generation)}}
 
 
 class StablePromotionVerifierTests(unittest.TestCase):
+    def test_confirmation_rejects_wrong_or_missing_token_for_every_stable_mutation(self):
+        for operation in ("promote", "repoint"):
+            for confirm in ("", "promote-beta"):
+                with self.subTest(operation=operation, confirm=confirm or "missing"):
+                    with self.assertRaisesRegex(ValueError, "confirm must be exactly"):
+                        CONFIRMATION.validate(operation=operation, confirm=confirm)
+            CONFIRMATION.validate(operation=operation, confirm="promote-stable")
+
+    def test_policy_requires_confirmation_before_authentication_or_mutation(self):
+        original = (ROOT / POLICY.WORKFLOW).read_text(encoding="utf-8")
+        mutations = (
+            original.replace("      - name: Require explicit Stable confirmation\n", "      - name: Confirmation moved too late\n", 1),
+            original.replace("--operation \"$OPERATION\" --confirm \"$CONFIRM\"", "--operation \"$OPERATION\" --confirm promote-beta", 1),
+        )
+        for changed in mutations:
+            with self.subTest(mutation=changed != original), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                workflow = root / POLICY.WORKFLOW
+                workflow.parent.mkdir(parents=True)
+                workflow.write_text(changed, encoding="utf-8")
+                self.assertTrue(POLICY.validate(workflow.read_text(encoding="utf-8")))
+
     def test_lost_response_retry_accepts_only_the_expected_next_generation(self):
         POINTER.verify(
             beta=_fields("target", 4),
diff --git a/.github/workflows/desktop_promote_beta.yml b/.github/workflows/desktop_promote_beta.yml
@@ -1,6 +1,9 @@
 name: Promote Qualified Desktop Beta
 
 on:
+  workflow_run:
+    workflows: ["Qualify Desktop Beta Candidate"]
+    types: [completed]
   workflow_dispatch:
     inputs:
       release_tag:
@@ -25,8 +28,23 @@ concurrency:
   group: desktop-beta-promotion
   cancel-in-progress: false
 
+env:
+  RELEASE_TAG: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || inputs.release_tag }}
+  QUALIFICATION_RUN_ID: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.id || inputs.qualification_run_id }}
+  AUTOMATIC_REQUEST: ${{ github.event_name == 'workflow_run' || inputs.automatic }}
+  QUALIFIER_EVENT_RUN_ID: ${{ github.event.workflow_run.id }}
+  QUALIFIER_EVENT_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+
 jobs:
   promote:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'workflow_dispatch' &&
+      github.event.workflow_run.repository.full_name == github.repository &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      github.event.workflow_run.path == '.github/workflows/desktop_qualify_beta.yml' &&
+      github.event.workflow_run.name == 'Qualify Desktop Beta Candidate')
     environment: prod
     runs-on: ubuntu-latest
     steps:
@@ -44,10 +62,9 @@ jobs:
           private-key: ${{ secrets.OMI_BOT_PRIVATE_KEY }}
 
       - name: Validate automatic beta request
-        if: ${{ inputs.automatic }}
+        if: ${{ env.AUTOMATIC_REQUEST == 'true' }}
         env:
           AUTO_BETA_ENABLED: ${{ vars.DESKTOP_AUTO_BETA_ENABLED }}
-          RELEASE_TAG: ${{ inputs.release_tag }}
         run: |
           set -euo pipefail
           if [[ "${AUTO_BETA_ENABLED,,}" == "false" ]]; then
@@ -68,18 +85,16 @@ jobs:
       - name: Download immutable qualification evidence
         uses: actions/download-artifact@v7
         with:
-          name: desktop-qualification-evidence-${{ inputs.release_tag }}
-          run-id: ${{ inputs.qualification_run_id }}
+          name: desktop-qualification-evidence-${{ env.RELEASE_TAG }}
+          run-id: ${{ env.QUALIFICATION_RUN_ID }}
           github-token: ${{ github.token }}
           path: /tmp/desktop-qualification-evidence
 
       - name: Download and validate qualified candidate
         id: candidate
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          RELEASE_TAG: ${{ inputs.release_tag }}
           REPO: ${{ github.repository }}
-          QUALIFICATION_RUN_ID: ${{ inputs.qualification_run_id }}
         run: |
           set -euo pipefail
           if ! printf '%s\n' "$RELEASE_TAG" | grep -qE '^v[0-9]+\.[0-9]+(\.[0-9]+)?\+[0-9]+-macos$'; then
@@ -96,9 +111,13 @@ jobs:
           test "$(jq -r .head_repository.full_name <<<"$run")" = "$REPO"
           test "$(jq -r .event <<<"$run")" = workflow_dispatch
           test "$(jq -r .path <<<"$run")" = .github/workflows/desktop_qualify_beta.yml
-          test "$(jq -r .head_branch <<<"$run")" = main
+          test "$(jq -r .head_branch <<<"$run")" = "$RELEASE_TAG"
           test "$(jq -r .name <<<"$run")" = 'Qualify Desktop Beta Candidate'
           test "$(jq -r .head_sha <<<"$run")" = "$TARGET_SHA"
+          if [[ "$GITHUB_EVENT_NAME" == workflow_run ]]; then
+            test "$QUALIFICATION_RUN_ID" = "$QUALIFIER_EVENT_RUN_ID"
+            test "$QUALIFIER_EVENT_HEAD_SHA" = "$TARGET_SHA"
+          fi
           gh release view "$RELEASE_TAG" --repo "$REPO" \
             --json tagName,body,isDraft,isPrerelease,publishedAt,assets \
             > /tmp/desktop-beta-release.json
@@ -154,7 +173,6 @@ jobs:
       - name: Advance explicit beta pointer
         env:
           PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
-          RELEASE_TAG: ${{ inputs.release_tag }}
         run: |
           set -euo pipefail
           ADMIN_KEY=$(gcloud secrets versions access latest --secret=ADMIN_KEY --project "$PROJECT_ID")
@@ -175,7 +193,6 @@ jobs:
       - name: Mark GitHub release live beta
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          RELEASE_TAG: ${{ inputs.release_tag }}
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
@@ -264,4 +281,4 @@ jobs:
           ADMIN_KEY=$(gcloud secrets versions access latest --secret=ADMIN_KEY --project "$PROJECT_ID")
           curl -fsS -X POST -H "secret-key: $ADMIN_KEY" \
             https://api.omi.me/v2/desktop/clear-cache >/dev/null
-          echo "Promoted ${{ inputs.release_tag }} to qualified beta." >> "$GITHUB_STEP_SUMMARY"
+          echo "Promoted $RELEASE_TAG to qualified beta." >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/desktop_promote_prod.yml b/.github/workflows/desktop_promote_prod.yml
@@ -52,6 +52,15 @@ jobs:
     environment: prod
     runs-on: ubuntu-latest
     steps:
+      - name: Require explicit Stable confirmation
+        env:
+          CONFIRM: ${{ inputs.confirm }}
+          OPERATION: ${{ inputs.operation }}
+        run: |
+          set -euo pipefail
+          python3 .github/scripts/require_stable_promotion_confirmation.py \
+            --operation "$OPERATION" --confirm "$CONFIRM"
+
       - name: Checkout promotion controls
         uses: actions/checkout@v7
         with:
@@ -72,11 +81,9 @@ jobs:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           REPO: ${{ github.repository }}
           RELEASE_TAG: ${{ inputs.release_tag }}
-          CONFIRM: ${{ inputs.confirm }}
           QUALIFICATION_RUN_ID: ${{ inputs.qualification_run_id }}
         run: |
           set -euo pipefail
-          test "$CONFIRM" = promote-stable || { echo 'confirm must be exactly: promote-stable' >&2; exit 1; }
           printf '%s\n' "$RELEASE_TAG" | grep -qE '^v[0-9]+\.[0-9]+(\.[0-9]+)?\+[0-9]+-macos$' || {
             echo "Invalid macOS release tag: $RELEASE_TAG" >&2; exit 1;
           }
diff --git a/.github/workflows/desktop_qualify_beta.yml b/.github/workflows/desktop_qualify_beta.yml
diff --git a/backend/tests/unit/test_desktop_release_scripts.py b/backend/tests/unit/test_desktop_release_scripts.py
diff --git a/desktop/macos/changelog/unreleased/20260721-beta-release-promotion-hardening.json b/desktop/macos/changelog/unreleased/20260721-beta-release-promotion-hardening.json
