Initiate and recover coherent beta releases from GitHub (#179)

Author: durable-workflow-ops

.github/workflows/build.yml

@@ -29,6 +29,7 @@ jobs:
           sh -n scripts/generate-homebrew-formula.sh
           sh -n scripts/verify-release.sh
           sh -n scripts/ci/check-docs-release-audit.sh
+          bash -n scripts/ci/verify-release-tag-source.sh
           bash -n scripts/verify-public-release-assets.sh
           bash -n scripts/verify-reproducible-build.sh
           pwsh -NoProfile -Command '$null = [scriptblock]::Create((Get-Content -Raw scripts/install.ps1))'

.github/workflows/release-plan-recovery.yml

@@ -62,6 +62,7 @@ jobs:
             gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" \
               -f ref="refs/tags/$RELEASE_TAG" -f sha="$RELEASE_COMMIT" >/dev/null
           fi
+          scripts/ci/verify-release-tag-source.sh
 
       - name: Start or resume repository-owned publication
         if: steps.recovery.outputs.action == 'publish'
@@ -72,6 +73,7 @@ jobs:
           RELEASE_COMMIT: ${{ steps.recovery.outputs.commit }}
         run: |
           set -euo pipefail
+          scripts/ci/verify-release-tag-source.sh
           decision=
           for attempt in 1 2 3 4 5 6; do
             gh run list --workflow release.yml --limit 100 \
@@ -90,7 +92,8 @@ jobs:
           done
           if [ "$publication_action" = dispatch ]; then
             gh workflow run release.yml --ref "$RELEASE_TAG" \
-              -f tag="$RELEASE_TAG" -f release_plan="$PLAN_TAG"
+              -f tag="$RELEASE_TAG" -f release_commit="$RELEASE_COMMIT" \
+              -f release_plan="$PLAN_TAG"
           elif [ "$publication_action" = rerun ]; then
             gh run rerun "$run_id"
           else

.github/workflows/release.yml

@@ -11,6 +11,9 @@ on:
       tag:
         description: 'Release tag (for manual dispatch, e.g. 0.0.1-test or v0.0.1-test)'
         required: true
+      release_commit:
+        description: 'Exact source commit declared by the immutable release plan'
+        required: true
       release_plan:
         description: 'Immutable release-plan tag initiating this recovery run'
         required: false
@@ -48,17 +51,22 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       tag: ${{ steps.resolve.outputs.tag }}
+      commit: ${{ steps.resolve.outputs.commit }}
     steps:
       - id: resolve
         shell: bash
         env:
           DISPATCH_TAG: ${{ inputs.tag }}
+          DISPATCH_COMMIT: ${{ inputs.release_commit }}
+          PUSH_COMMIT: ${{ github.sha }}
         run: |
           set -euo pipefail
           if [ "$GITHUB_EVENT_NAME" = "workflow_dispatch" ]; then
             tag="$DISPATCH_TAG"
+            commit="$DISPATCH_COMMIT"
           else
             tag="${GITHUB_REF_NAME}"
+            commit="$PUSH_COMMIT"
           fi
 
           if [ -z "$tag" ]; then
@@ -73,9 +81,14 @@ jobs:
             echo "::error::Invalid release tag: $raw_tag"
             exit 1
           fi
+          if ! printf '%s\n' "$commit" | grep -Eq '^[0-9a-f]{40}$'; then
+            echo "::error::Release commit must be a full lowercase Git commit SHA"
+            exit 1
+          fi
 
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
-          echo "Resolved release tag: $tag"
+          echo "commit=$commit" >> "$GITHUB_OUTPUT"
+          echo "Resolved release tag $tag at immutable commit $commit"
 
   release-preflight:
     name: Release preflight
@@ -86,7 +99,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ needs.resolve-release.outputs.tag }}
+          ref: ${{ needs.resolve-release.outputs.commit }}
+
+      - name: Verify expected release source
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.resolve-release.outputs.tag }}
+          RELEASE_COMMIT: ${{ needs.resolve-release.outputs.commit }}
+        run: scripts/ci/verify-release-tag-source.sh
 
       - name: Inspect existing public release assets
         id: public_assets
@@ -199,7 +219,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          ref: ${{ needs.resolve-release.outputs.tag }}
+          ref: ${{ needs.resolve-release.outputs.commit }}
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
@@ -276,7 +296,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ needs.resolve-release.outputs.tag }}
+          ref: ${{ needs.resolve-release.outputs.commit }}
 
       - name: Download PHAR artifact
         uses: actions/download-artifact@v4
@@ -387,7 +407,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ needs.resolve-release.outputs.tag }}
+          ref: ${{ needs.resolve-release.outputs.commit }}
 
       - name: Download PHAR artifact
         uses: actions/download-artifact@v4
@@ -547,7 +567,19 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          ref: ${{ needs.resolve-release.outputs.tag }}
+          ref: ${{ needs.resolve-release.outputs.commit }}
+
+      - name: Resolve exact source identity
+        env:
+          EXPECTED_COMMIT: ${{ needs.resolve-release.outputs.commit }}
+        run: |
+          set -euo pipefail
+          head_commit="$(git rev-parse HEAD)"
+          if [ "$head_commit" != "$EXPECTED_COMMIT" ]; then
+            printf 'release checkout %s does not match expected commit %s\n' \
+              "$head_commit" "$EXPECTED_COMMIT" >&2
+            exit 1
+          fi
 
       - name: Download release artifacts
         uses: actions/download-artifact@v4
@@ -593,6 +625,13 @@ jobs:
         working-directory: dist
         run: sha256sum -- * > SHA256SUMS
 
+      - name: Verify immutable release tag at publication boundary
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.resolve-release.outputs.tag }}
+          RELEASE_COMMIT: ${{ needs.resolve-release.outputs.commit }}
+        run: scripts/ci/verify-release-tag-source.sh
+
       - name: Attest release artifacts
         uses: actions/attest-build-provenance@v2
         with:

scripts/ci/component-release-recovery.py

@@ -783,11 +783,12 @@ def base_state(component: str, tag: str | None = None, plan: dict[str, Any] | No
 def resolve_component(
     client: PublicClient,
     component_name: str,
-    requested_tag: str | None,
+    tag: str,
+    record_commit: str,
+    plan: dict[str, Any],
 ) -> tuple[dict[str, Any], dict[str, str]]:
     if component_name not in COMPONENTS:
         raise RecoveryError(f"unknown release component: {component_name}")
-    tag, record_commit, plan = discover_plan(client, requested_tag)
     branches, recovery_workflows = verify_plan_authority(client, plan)
     component = COMPONENTS[component_name]
     identity = plan["components"][component_name]
@@ -920,13 +921,13 @@ def main() -> int:
                 )
             )
         elif args.command == "resolve":
-            tag: str | None = None
+            tag: str | None = args.plan_tag
+            record_commit: str | None = None
             plan: dict[str, Any] | None = None
             try:
-                state, outputs = resolve_component(client, args.component, args.plan_tag)
-                tag = outputs["plan_tag"]
-                plan = discover_plan(client, tag)[2]
+                tag, record_commit, plan = discover_plan(client, args.plan_tag)
                 args.plan_output.write_bytes(canonical_json(plan))
+                state, outputs = resolve_component(client, args.component, tag, record_commit, plan)
                 args.evidence.write_bytes(canonical_json(state))
                 write_output(args.github_output, outputs)
             except RecoveryError as error:
@@ -948,6 +949,8 @@ def main() -> int:
                     write_output(args.github_output, {"action": "none"})
                     return 0
                 failure = base_state(args.component, tag, plan)
+                if record_commit is not None:
+                    failure["plan_record_commit"] = record_commit
                 failure.update(
                     {
                         "phase": error.phase,

scripts/ci/verify-release-tag-source.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+fail() {
+    printf 'Release tag source verification failed: %s\n' "$1" >&2
+    exit 1
+}
+
+release_tag="${RELEASE_TAG:-}"
+release_commit="${RELEASE_COMMIT:-}"
+repository="${GITHUB_REPOSITORY:-}"
+gh_cli="${GH_CLI:-gh}"
+
+[[ "$release_tag" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z][0-9A-Za-z.-]*)?$ ]] \
+    || fail "RELEASE_TAG must be an exact release version."
+[[ "$release_commit" =~ ^[0-9a-f]{40}$ ]] \
+    || fail "RELEASE_COMMIT must be a full lowercase Git commit SHA."
+[[ "$repository" =~ ^[0-9A-Za-z_.-]+/[0-9A-Za-z_.-]+$ ]] \
+    || fail "GITHUB_REPOSITORY must identify the release repository."
+
+if ! target="$("$gh_cli" api "repos/$repository/git/ref/tags/$release_tag" \
+    --jq '.object.type + " " + .object.sha' 2>/dev/null)"; then
+    fail "public tag $release_tag does not exist."
+fi
+
+read -r object_type object_sha <<< "$target"
+depth=0
+while [ "$object_type" = tag ]; do
+    [[ "$object_sha" =~ ^[0-9a-f]{40}$ ]] \
+        || fail "public tag $release_tag has an invalid annotated-tag target."
+    depth=$((depth + 1))
+    [ "$depth" -le 16 ] || fail "public tag $release_tag has an invalid annotated-tag chain."
+    if ! target="$("$gh_cli" api "repos/$repository/git/tags/$object_sha" \
+        --jq '.object.type + " " + .object.sha' 2>/dev/null)"; then
+        fail "public tag $release_tag has an unreadable annotated-tag target."
+    fi
+    read -r object_type object_sha <<< "$target"
+done
+
+[ "$object_type" = commit ] \
+    || fail "public tag $release_tag does not resolve to a commit."
+[[ "$object_sha" =~ ^[0-9a-f]{40}$ ]] \
+    || fail "public tag $release_tag resolves to an invalid commit identity."
+[ "$object_sha" = "$release_commit" ] \
+    || fail "public tag $release_tag points to $object_sha, not planned commit $release_commit."
+
+printf 'Verified public tag %s at planned commit %s.\n' "$release_tag" "$release_commit"

tests/ReleaseInstallerContractTest.php

@@ -5,6 +5,7 @@
 namespace Tests;
 
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Process\Process;
 
 final class ReleaseInstallerContractTest extends TestCase
 {
@@ -17,7 +18,7 @@ public function test_installers_are_versioned_release_assets(): void
         self::assertStringContainsString('0.0.1-test or v0.0.1-test', $releaseWorkflow);
         self::assertStringContainsString('raw_tag="$tag"', $releaseWorkflow);
         self::assertStringContainsString('tag="${tag#v}"', $releaseWorkflow);
-        self::assertStringContainsString('ref: ${{ needs.resolve-release.outputs.tag }}', $releaseWorkflow);
+        self::assertStringContainsString('ref: ${{ needs.resolve-release.outputs.commit }}', $releaseWorkflow);
         self::assertStringContainsString('DW_CLI_VERSION: ${{ needs.resolve-release.outputs.tag }}', $releaseWorkflow);
         self::assertStringContainsString('DW_CLI_COMMIT="$(git rev-parse HEAD)"', $releaseWorkflow);
         self::assertStringContainsString('release-preflight:', $releaseWorkflow);
@@ -95,9 +96,114 @@ public function test_build_validates_installer_scripts(): void
         self::assertStringContainsString('sh -n scripts/verify-release.sh', $buildWorkflow);
         self::assertStringContainsString('bash -n scripts/verify-public-release-assets.sh', $buildWorkflow);
         self::assertStringContainsString('sh -n scripts/ci/check-docs-release-audit.sh', $buildWorkflow);
+        self::assertStringContainsString('bash -n scripts/ci/verify-release-tag-source.sh', $buildWorkflow);
         self::assertStringContainsString('scripts/install.ps1', $buildWorkflow);
     }
 
+    public function test_release_recovery_retains_the_planned_commit_at_publication(): void
+    {
+        $releaseWorkflow = self::readRepoFile('.github/workflows/release.yml');
+        $recoveryWorkflow = self::readRepoFile('.github/workflows/release-plan-recovery.yml');
+
+        self::assertStringContainsString('release_commit:', $releaseWorkflow);
+        self::assertStringContainsString('commit: ${{ steps.resolve.outputs.commit }}', $releaseWorkflow);
+        self::assertStringContainsString('DISPATCH_COMMIT: ${{ inputs.release_commit }}', $releaseWorkflow);
+        self::assertStringContainsString('PUSH_COMMIT: ${{ github.sha }}', $releaseWorkflow);
+        self::assertSame(5, substr_count($releaseWorkflow, 'ref: ${{ needs.resolve-release.outputs.commit }}'));
+        self::assertStringNotContainsString('|| github.ref }}', $releaseWorkflow);
+        self::assertStringContainsString('EXPECTED_COMMIT: ${{ needs.resolve-release.outputs.commit }}', $releaseWorkflow);
+        self::assertSame(2, substr_count($releaseWorkflow, 'RELEASE_COMMIT: ${{ needs.resolve-release.outputs.commit }}'));
+        self::assertStringContainsString('-f release_commit="$RELEASE_COMMIT"', $recoveryWorkflow);
+        self::assertSame(2, substr_count($recoveryWorkflow, 'scripts/ci/verify-release-tag-source.sh'));
+
+        $sourceCheck = strpos($releaseWorkflow, 'Resolve exact source identity');
+        $boundaryCheck = strpos($releaseWorkflow, 'Verify immutable release tag at publication boundary');
+        $attestation = strpos($releaseWorkflow, 'Attest release artifacts');
+        $publication = strpos($releaseWorkflow, 'Create GitHub Release');
+        self::assertIsInt($sourceCheck);
+        self::assertIsInt($boundaryCheck);
+        self::assertIsInt($attestation);
+        self::assertIsInt($publication);
+        self::assertLessThan($boundaryCheck, $sourceCheck);
+        self::assertLessThan($attestation, $boundaryCheck);
+        self::assertLessThan($publication, $boundaryCheck);
+    }
+
+    public function test_recovery_reused_push_run_rejects_tag_movement_before_publication(): void
+    {
+        $releaseWorkflow = self::readRepoFile('.github/workflows/release.yml');
+        $plannedCommit = str_repeat('a', 40);
+        $movedCommit = str_repeat('b', 40);
+        $temporary = sys_get_temp_dir().'/cli-release-tag-'.bin2hex(random_bytes(4));
+        self::assertTrue(mkdir($temporary));
+        $fakeGh = $temporary.'/gh';
+        $publicationRuns = $temporary.'/publication-runs.json';
+        file_put_contents($fakeGh, <<<'SH'
+#!/usr/bin/env sh
+set -eu
+printf 'commit %s\n' "$FAKE_TAG_SHA"
+SH);
+        self::assertTrue(chmod($fakeGh, 0755));
+        file_put_contents($publicationRuns, json_encode([
+            [
+                'databaseId' => 1234,
+                'displayTitle' => 'Release 1.2.3-alpha.4 for direct',
+                'event' => 'push',
+                'headBranch' => '1.2.3-alpha.4',
+                'headSha' => $plannedCommit,
+                'status' => 'in_progress',
+                'conclusion' => null,
+            ],
+        ], JSON_THROW_ON_ERROR));
+
+        self::assertStringContainsString('PUSH_COMMIT: ${{ github.sha }}', $releaseWorkflow);
+        self::assertSame(5, substr_count($releaseWorkflow, 'ref: ${{ needs.resolve-release.outputs.commit }}'));
+        self::assertSame(2, substr_count($releaseWorkflow, 'RELEASE_COMMIT: ${{ needs.resolve-release.outputs.commit }}'));
+
+        $environment = [
+            'GH_CLI' => $fakeGh,
+            'GITHUB_REPOSITORY' => 'durable-workflow/cli',
+            'RELEASE_TAG' => '1.2.3-alpha.4',
+            'RELEASE_COMMIT' => $plannedCommit,
+        ];
+
+        try {
+            $selection = new Process([
+                'python3',
+                dirname(__DIR__).'/scripts/ci/component-release-recovery.py',
+                'select-publication-run',
+                '--release-tag',
+                '1.2.3-alpha.4',
+                '--release-commit',
+                $plannedCommit,
+                '--runs',
+                $publicationRuns,
+            ], dirname(__DIR__));
+            self::assertSame(0, $selection->run(), $selection->getErrorOutput());
+            self::assertSame("wait\t1234\tin_progress\t\n", $selection->getOutput());
+
+            $exact = new Process(
+                [dirname(__DIR__).'/scripts/ci/verify-release-tag-source.sh'],
+                dirname(__DIR__),
+                $environment + ['FAKE_TAG_SHA' => $plannedCommit],
+            );
+            self::assertSame(0, $exact->run(), $exact->getErrorOutput());
+
+            $moved = new Process(
+                [dirname(__DIR__).'/scripts/ci/verify-release-tag-source.sh'],
+                dirname(__DIR__),
+                $environment + ['FAKE_TAG_SHA' => $movedCommit],
+            );
+            self::assertSame(1, $moved->run());
+            self::assertStringContainsString($movedCommit, $moved->getErrorOutput());
+            self::assertStringContainsString($plannedCommit, $moved->getErrorOutput());
+        } finally {
+            @unlink($fakeGh);
+            @unlink($publicationRuns);
+            @rmdir($temporary);
+        }
+    }
+
     public function test_release_includes_checksum_and_attestation_verifier(): void
     {
         $verifier = self::readRepoFile('scripts/verify-release.sh');