Gate release publication on immutable setting

scripts/check-github-release-immutability.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+# Fail closed unless GitHub confirms that future releases in this repository
+# will become immutable when a staged draft is published. The endpoint requires
+# repository Administration (read), so callers must supply an explicit token
+# with that narrow read capability rather than treating an anonymous 404 as a
+# disabled setting.
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+    echo "Usage: $0 <owner/repo>" >&2
+    exit 1
+fi
+
+REPO="$1"
+if [[ ! "$REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+    echo "Invalid GitHub repository: ${REPO}" >&2
+    exit 1
+fi
+if [ -z "${GH_TOKEN:-}" ]; then
+    echo "GH_TOKEN with repository Administration (read) is required to prove release immutability." >&2
+    exit 1
+fi
+
+for command in gh jq; do
+    if ! command -v "$command" >/dev/null 2>&1; then
+        echo "${command} is required to check GitHub release immutability." >&2
+        exit 1
+    fi
+done
+
+setting_json="$(mktemp)"
+cleanup() {
+    rm -f "$setting_json"
+}
+trap cleanup EXIT
+
+if ! gh api \
+    -H 'Accept: application/vnd.github+json' \
+    -H 'X-GitHub-Api-Version: 2026-03-10' \
+    "repos/${REPO}/immutable-releases" > "$setting_json"; then
+    echo "GitHub did not confirm immutable releases for ${REPO}; the setting may be disabled or the token may lack Administration (read)." >&2
+    exit 1
+fi
+
+if ! jq -e \
+    '.enabled == true and (.enforced_by_owner | type == "boolean")' \
+    "$setting_json" >/dev/null; then
+    jq -c '{enabled, enforced_by_owner}' "$setting_json" >&2 || true
+    echo "Immutable releases are not enabled for ${REPO}; refusing to cross the publication boundary." >&2
+    exit 1
+fi
+
+enforced_by_owner="$(jq -r '.enforced_by_owner // false' "$setting_json")"
+echo "[OK] GitHub immutable releases are enabled for ${REPO} (enforced_by_owner=${enforced_by_owner})."

scripts/release_control/check_github_release_immutability_test.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import textwrap
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPT = ROOT / "scripts" / "check-github-release-immutability.sh"
+
+
+class CheckGitHubReleaseImmutabilityTest(unittest.TestCase):
+    def run_check(
+        self,
+        response: object = None,
+        *,
+        api_succeeds: bool = True,
+        include_token: bool = True,
+        repository: str = "rcourtman/Pulse",
+    ):
+        if response is None:
+            response = {"enabled": True, "enforced_by_owner": False}
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            calls = root / "calls"
+            fake_gh = root / "gh"
+            fake_gh.write_text(
+                textwrap.dedent(
+                    f"""\
+                    #!/usr/bin/env bash
+                    set -euo pipefail
+                    printf '%s\\n' "$*" >> {calls!s}
+                    cat <<'JSON'
+                    {json.dumps(response)}
+                    JSON
+                    exit {0 if api_succeeds else 1}
+                    """
+                ),
+                encoding="utf-8",
+            )
+            fake_gh.chmod(0o755)
+            env = os.environ.copy()
+            env["PATH"] = f"{root}:{env['PATH']}"
+            if include_token:
+                env["GH_TOKEN"] = "test-token"
+            else:
+                env.pop("GH_TOKEN", None)
+            result = subprocess.run(
+                [str(SCRIPT), repository],
+                cwd=ROOT,
+                env=env,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+            call_text = calls.read_text(encoding="utf-8") if calls.exists() else ""
+            return result, call_text
+
+    def test_accepts_enabled_repository_setting(self) -> None:
+        result, calls = self.run_check()
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("immutable releases are enabled", result.stdout)
+        self.assertIn("repos/rcourtman/Pulse/immutable-releases", calls)
+        self.assertIn("X-GitHub-Api-Version: 2026-03-10", calls)
+
+    def test_rejects_disabled_repository_setting(self) -> None:
+        result, _ = self.run_check(
+            {"enabled": False, "enforced_by_owner": False}
+        )
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("refusing to cross the publication boundary", result.stderr)
+
+    def test_rejects_unavailable_or_unauthorized_setting(self) -> None:
+        result, _ = self.run_check(api_succeeds=False)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("may be disabled or the token may lack", result.stderr)
+
+    def test_rejects_malformed_success_response(self) -> None:
+        result, _ = self.run_check({"enforced_by_owner": False})
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("not enabled", result.stderr)
+
+        result, _ = self.run_check(
+            {"enabled": True, "enforced_by_owner": "false"}
+        )
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("not enabled", result.stderr)
+
+    def test_requires_explicit_administration_read_token(self) -> None:
+        result, calls = self.run_check(include_token=False)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("Administration (read) is required", result.stderr)
+        self.assertEqual(calls, "")
+
+    def test_rejects_invalid_repository_before_api_call(self) -> None:
+        result, calls = self.run_check(repository="not-a-repository")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("Invalid GitHub repository", result.stderr)
+        self.assertEqual(calls, "")
+
+
+if __name__ == "__main__":
+    unittest.main()

scripts/release_control/release_promotion_policy_test.py

@@ -351,6 +351,8 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
         dispatch = workflow_job_block(workflow, "dispatch_release_convergence")
         activation = workflow_job_block(workflow, "activate_release")
         commit_verdict = workflow_job_block(workflow, "release_commit_verdict")
+        recovery = read(".github/workflows/recover-release-activation.yml")
+        recovery_activation = workflow_job_block(recovery, "recover_activation")
 
         for dependency in (
             "create_release",
@@ -402,6 +404,20 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
         self.assertIn("verify-github-release-integrity.sh", activation)
         self.assertIn("verify-github-release-integrity.sh", convergence)
         self.assertIn("verify-github-release-integrity.sh", commit_verdict)
+        for publication_job in (activation, recovery_activation):
+            with self.subTest(publication_job=publication_job[:40]):
+                self.assertIn(
+                    "IMMUTABILITY_ADMIN_TOKEN: ${{ secrets.WORKFLOW_PAT }}",
+                    publication_job,
+                )
+                self.assertIn("check-github-release-immutability.sh", publication_job)
+                setting_check = publication_job.index(
+                    "check-github-release-immutability.sh"
+                )
+                self.assertLess(
+                    setting_check,
+                    publication_job.index('-X PATCH --input', setting_check),
+                )
         marker_upload = activation.index('gh release upload "${TAG}"')
         publish_patch = activation.index(
             '-X PATCH --input "$publish_payload"', marker_upload
@@ -779,7 +795,10 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
             '.status == "completed" and .conclusion == "success"', verdict
         )
         self.assertLess(
-            activation.index("require_viable_convergence_owner\n          gh api"),
+            activation.index(
+                "require_viable_convergence_owner\n"
+                "          if [ -z \"${IMMUTABILITY_ADMIN_TOKEN:-}\" ]"
+            ),
             activation.index("-X PATCH --input \"$publish_payload\""),
         )
         marker_upload = activation.index('gh release upload "${TAG}"')