ci(preview): stabilize Cloudflare preview deployments (#2062)

* ci(preview): stabilize Cloudflare preview deployments

* ci(preview): bound diagnostics and cover artifact fallback

* ci(preview): isolate artifact deploy permissions

* ci(preview): tidy deployment comment rendering

* ci(preview): harden preview manifest generation

* ci(preview): fail on preview diagnostics failure

.github/workflows/preview-deploy.yml

@@ -23,82 +23,71 @@ jobs:
     outputs:
       artifact_name: ${{ steps.preview.outputs.artifact_name }}
       head_sha: ${{ steps.preview.outputs.head_sha }}
+      is_fork: ${{ steps.preview.outputs.is_fork }}
       pr_number: ${{ steps.preview.outputs.pr_number }}
       should_deploy: ${{ steps.preview.outputs.should_deploy }}
 
     steps:
+      - name: Checkout trusted preview resolver
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          path: trusted-preview-resolver
+          persist-credentials: false
+          sparse-checkout: |
+            workers/preview/deploy
+
       - name: Resolve preview request
         id: preview
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           script: |
-            const workflowRun = context.payload.workflow_run;
-            const runPr = workflowRun.pull_requests?.[0];
+            const { resolvePreviewRequest } = require('./trusted-preview-resolver/workers/preview/deploy/resolve_preview_request.cjs');
+            await resolvePreviewRequest({ github, context, core });
 
-            core.setOutput('should_deploy', 'false');
-
-            if (!runPr) {
-              core.info('Workflow run is not associated with a pull request');
-              return;
-            }
-
-            const prNumber = runPr.number;
-            const headSha = workflowRun.head_sha;
-
-            const { data: pullRequest } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-            });
-
-            if (pullRequest.head.sha !== headSha) {
-              core.setFailed(`Workflow run head SHA ${headSha} does not match PR head ${pullRequest.head.sha}`);
-              return;
-            }
-
-            const hasPreviewLabel = pullRequest.labels.some((label) => label.name === 'preview-cf');
-            if (!hasPreviewLabel) {
-              core.info(`PR ${prNumber} does not have the preview-cf label`);
-              return;
-            }
-
-            const files = await github.paginate(github.rest.pulls.listFiles, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-              per_page: 100,
-            });
-            const workflowChanges = files
-              .map((file) => file.filename)
-              .filter((filename) => filename.startsWith('.github/workflows/'));
-
-            if (workflowChanges.length > 0) {
-              core.setFailed(`Preview deployment requires base-trusted workflow definitions; changed workflow files: ${workflowChanges.join(', ')}`);
-              return;
-            }
-
-            const artifactName = `preview-image-pr-${prNumber}-${headSha}`;
-            const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: workflowRun.id,
-              per_page: 100,
-            });
-            const artifact = artifacts.find((item) => item.name === artifactName && !item.expired);
-
-            if (!artifact) {
-              core.setFailed(`Pull Request workflow run ${workflowRun.id} did not publish ${artifactName}`);
-              return;
-            }
-
-            core.setOutput('artifact_name', artifactName);
-            core.setOutput('head_sha', headSha);
-            core.setOutput('pr_number', String(prNumber));
-            core.setOutput('should_deploy', 'true');
-
-  deploy-preview:
+  deployment_record:
     needs: preview-gate
     if: needs.preview-gate.outputs.should_deploy == 'true'
+    name: Create GitHub Deployment
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      deployments: write
+    outputs:
+      deployment_id: ${{ steps.deployment.outputs.result }}
+    env:
+      HEAD_SHA: ${{ needs.preview-gate.outputs.head_sha }}
+      IS_FORK: ${{ needs.preview-gate.outputs.is_fork }}
+      PR_NUMBER: ${{ needs.preview-gate.outputs.pr_number }}
+
+    steps:
+      - name: Create GitHub Deployment
+        if: env.IS_FORK == 'false'
+        id: deployment
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        with:
+          script: |
+            const prNumber = process.env.PR_NUMBER;
+            const headSha = process.env.HEAD_SHA;
+            const deployment = await github.rest.repos.createDeployment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: headSha,
+              environment: `preview-pr-${prNumber}`,
+              auto_merge: false,
+              required_contexts: [],
+              description: 'PR Preview Deployment'
+            });
+            return deployment.data.id;
+          result-encoding: string
+
+  deploy-preview:
+    needs: [preview-gate, deployment_record]
+    if: |
+      always() &&
+      needs.preview-gate.outputs.should_deploy == 'true' &&
+      (needs.deployment_record.result == 'success' || needs.deployment_record.result == 'skipped')
     name: Deploy to Cloudflare Containers
     runs-on: ubuntu-latest
     timeout-minutes: 45
@@ -109,11 +98,12 @@ jobs:
     permissions:
       actions: read
       contents: read
-      pull-requests: write
-      deployments: write
+    outputs:
+      preview_url: ${{ steps.deploy.outputs.preview_url }}
     env:
       ARTIFACT_NAME: ${{ needs.preview-gate.outputs.artifact_name }}
       HEAD_SHA: ${{ needs.preview-gate.outputs.head_sha }}
+      IS_FORK: ${{ needs.preview-gate.outputs.is_fork }}
       PR_NUMBER: ${{ needs.preview-gate.outputs.pr_number }}
 
     steps:
@@ -134,15 +124,35 @@ jobs:
           github-token: ${{ github.token }}
           path: ${{ runner.temp }}/preview-image
 
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: "24"
+
       - name: Verify preview image artifact checksum
         run: |
           set -euo pipefail
 
           image_archive="$RUNNER_TEMP/preview-image/sure-preview-image.tar.gz"
           checksum_file="$RUNNER_TEMP/preview-image/sure-preview-image.sha256"
+          manifest_file="$RUNNER_TEMP/preview-image/sure-preview-image.manifest.json"
+          expected_files="$(mktemp)"
+          actual_files="$(mktemp)"
 
           test -f "$image_archive"
           test -f "$checksum_file"
+          test -f "$manifest_file"
+
+          printf '%s\n' \
+            sure-preview-image.manifest.json \
+            sure-preview-image.sha256 \
+            sure-preview-image.tar.gz | sort > "$expected_files"
+          find "$RUNNER_TEMP/preview-image" -maxdepth 1 -type f -printf '%f\n' | sort > "$actual_files"
+
+          if ! diff -u "$expected_files" "$actual_files"; then
+            echo "Preview image artifact contained unexpected files" >&2
+            exit 1
+          fi
 
           expected_checksum="$(tr -d '[:space:]' < "$checksum_file")"
           actual_checksum="$(sha256sum "$image_archive" | awk '{print $1}')"
@@ -152,10 +162,32 @@ jobs:
             exit 1
           fi
 
-      - name: Setup Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: "24"
+          node - "$manifest_file" "$expected_checksum" <<'NODE'
+          const fs = require('node:fs');
+
+          const manifestPath = process.argv[2];
+          const expectedChecksum = process.argv[3];
+          const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+          const expectedImageTag = `sure-preview-pr-${process.env.PR_NUMBER}:${process.env.HEAD_SHA}`;
+          const expected = {
+            artifactVersion: 1,
+            archivePath: 'sure-preview-image.tar.gz',
+            archiveSha256: expectedChecksum,
+            headSha: process.env.HEAD_SHA,
+            imageTag: expectedImageTag,
+            prNumber: process.env.PR_NUMBER,
+          };
+
+          for (const [key, value] of Object.entries(expected)) {
+            if (manifest[key] !== value) {
+              throw new Error(`Preview image manifest ${key} mismatch`);
+            }
+          }
+
+          if (!/^sha256:[a-f0-9]{64}$/.test(manifest.imageId || '')) {
+            throw new Error('Preview image manifest imageId is invalid');
+          }
+          NODE
 
       - name: Prepare trusted preview deploy workspace
         run: |
@@ -182,10 +214,18 @@ jobs:
           set -euo pipefail
 
           image_archive="$RUNNER_TEMP/preview-image/sure-preview-image.tar.gz"
+          manifest_file="$RUNNER_TEMP/preview-image/sure-preview-image.manifest.json"
           expected_image="sure-preview-pr-${PR_NUMBER}:${HEAD_SHA}"
 
           gzip -dc "$image_archive" | docker load
           docker image inspect "$expected_image" >/dev/null
+          expected_image_id="$(node -e 'const fs = require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).imageId);' "$manifest_file")"
+          actual_image_id="$(docker image inspect --format '{{.Id}}' "$expected_image")"
+
+          if [ "$expected_image_id" != "$actual_image_id" ]; then
+            echo "Loaded preview image ID did not match artifact manifest" >&2
+            exit 1
+          fi
 
       - name: Push preview image to Cloudflare registry
         id: image
@@ -239,25 +279,6 @@ jobs:
 
           cat "$config_path"
 
-      - name: Create GitHub Deployment
-        id: deployment
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
-        with:
-          script: |
-            const prNumber = process.env.PR_NUMBER;
-            const headSha = process.env.HEAD_SHA;
-            const deployment = await github.rest.repos.createDeployment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              ref: headSha,
-              environment: `preview-pr-${prNumber}`,
-              auto_merge: false,
-              required_contexts: [],
-              description: 'PR Preview Deployment'
-            });
-            return deployment.data.id;
-          result-encoding: string
-
       - name: Deploy to Cloudflare Containers
         id: deploy
         env:
@@ -268,7 +289,26 @@ jobs:
           set -euo pipefail
 
           cd "$RUNNER_TEMP/sure-preview-worker"
-          ./node_modules/.bin/wrangler deploy --config wrangler.toml --var "PR_NUMBER:${PR_NUMBER}"
+          deploy_log="$RUNNER_TEMP/wrangler-deploy.log"
+          clean_deploy_log="$RUNNER_TEMP/wrangler-deploy.clean.log"
+
+          deploy_once() {
+            ./node_modules/.bin/wrangler deploy --config wrangler.toml --var "PR_NUMBER:${PR_NUMBER}" 2>&1 | tee "$deploy_log"
+          }
+
+          if ! deploy_once; then
+            perl -pe 's/\e\[[0-9;]*[A-Za-z]//g' "$deploy_log" > "$clean_deploy_log"
+
+            if grep -F "associated with a different durable object namespace" "$clean_deploy_log" >/dev/null; then
+              echo "Detected stale Cloudflare container app state for PR ${PR_NUMBER}; deleting preview Worker and retrying once."
+              if ! ./node_modules/.bin/wrangler delete --name "sure-preview-${PR_NUMBER}" --force; then
+                echo "Preview Worker delete failed; continuing to the single retry so wrangler deploy reports the final error if the stale state remains." >&2
+              fi
+              deploy_once
+            else
+              exit 1
+            fi
+          fi
 
           # Get the deployment URL
           PREVIEW_URL="https://sure-preview-${PR_NUMBER}.${CLOUDFLARE_WORKERS_SUBDOMAIN}.workers.dev"
@@ -279,17 +319,85 @@ jobs:
           PREVIEW_URL: ${{ steps.deploy.outputs.preview_url }}
         run: |
           echo "Triggering preview wake-up..."
-          curl -fsS "$PREVIEW_URL/" >/dev/null || true
+          curl -fsS --connect-timeout 5 --max-time 15 "$PREVIEW_URL/_container_status" >/dev/null || true
 
-      - name: Update Deployment Status
-        if: always() && steps.deployment.outputs.result
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+      - name: Collect preview diagnostics
+        if: success()
         env:
-          DEPLOYMENT_ID: ${{ steps.deployment.outputs.result }}
           PREVIEW_URL: ${{ steps.deploy.outputs.preview_url }}
+        run: |
+          set -euo pipefail
+
+          diagnostics_file="$RUNNER_TEMP/preview-diagnostics.json"
+          last_error=""
+
+          for attempt in $(seq 1 20); do
+            if curl -fsS --connect-timeout 5 --max-time 15 "$PREVIEW_URL/_container_status" -o "$diagnostics_file"; then
+              if jq -e '.previewReady == true or .previewFailed == true' "$diagnostics_file" >/dev/null; then
+                break
+              fi
+            else
+              last_error="curl failed on attempt ${attempt}"
+            fi
+
+            sleep 3
+          done
+
+          if [ ! -s "$diagnostics_file" ]; then
+            jq -n --arg error "${last_error:-preview diagnostics unavailable}" \
+              --arg url "$PREVIEW_URL" \
+              '{previewReady: false, previewFailed: false, error: $error, previewUrl: $url}' > "$diagnostics_file"
+          fi
+
+          jq -c . "$diagnostics_file"
+
+          if jq -e '.previewFailed == true' "$diagnostics_file" >/dev/null; then
+            echo "Preview diagnostics from _container_status reported previewFailed=true:" >&2
+            jq -c . "$diagnostics_file" >&2
+            exit 1
+          fi
+
+      - name: Upload preview diagnostics
+        if: success()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: preview-diagnostics-pr-${{ env.PR_NUMBER }}-${{ env.HEAD_SHA }}
+          path: ${{ runner.temp }}/preview-diagnostics.json
+          if-no-files-found: error
+          retention-days: 3
+
+      - name: Store cleanup metadata
+        if: success()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: preview-cleanup-pr-${{ env.PR_NUMBER }}
+          path: ${{ runner.temp }}/sure-preview-worker/wrangler.toml
+          retention-days: 2
+
+  deployment_status:
+    needs: [preview-gate, deployment_record, deploy-preview]
+    if: |
+      always() &&
+      needs.preview-gate.outputs.should_deploy == 'true' &&
+      needs.preview-gate.outputs.is_fork == 'false' &&
+      needs.deployment_record.result == 'success'
+    name: Update GitHub Deployment Status
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      deployments: write
+    env:
+      DEPLOYMENT_ID: ${{ needs.deployment_record.outputs.deployment_id }}
+      DEPLOY_RESULT: ${{ needs.deploy-preview.result }}
+      PREVIEW_URL: ${{ needs.deploy-preview.outputs.preview_url }}
+
+    steps:
+      - name: Update Deployment Status
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           script: |
-            const state = '${{ job.status }}' === 'success' ? 'success' : 'failure';
+            const state = process.env.DEPLOY_RESULT === 'success' ? 'success' : 'failure';
             const previewUrl = process.env.PREVIEW_URL || undefined;
             await github.rest.repos.createDeploymentStatus({
               owner: context.repo.owner,
@@ -300,27 +408,41 @@ jobs:
               description: state === 'success' ? 'Preview deployed successfully' : 'Preview deployment failed'
             });
 
+  preview_comment:
+    needs: [preview-gate, deploy-preview]
+    if: needs.deploy-preview.result == 'success'
+    name: Comment on PR
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: write
+    env:
+      HEAD_SHA: ${{ needs.preview-gate.outputs.head_sha }}
+      PR_NUMBER: ${{ needs.preview-gate.outputs.pr_number }}
+      PREVIEW_URL: ${{ needs.deploy-preview.outputs.preview_url }}
+
+    steps:
       - name: Comment on PR
-        if: success()
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
-        env:
-          PREVIEW_URL: ${{ steps.deploy.outputs.preview_url }}
         with:
           script: |
             const previewUrl = process.env.PREVIEW_URL;
             const issueNumber = Number(process.env.PR_NUMBER);
             const headSha = process.env.HEAD_SHA;
-            const commentBody = `## 🚀 Preview Deployment Ready
-
-            Your preview environment has been deployed to Cloudflare Containers with the PR's Docker image.
-
-            **Preview URL:** ${previewUrl}
-
-            > ⏰ This preview is intended to be cleaned up after **24 hours** of the last deployment once the cleanup workflow is live on the default branch.
-            > 💤 The container will sleep after 30 minutes of inactivity and wake on the next request.
-
-            ---
-            <sub>Deployed from commit ${headSha}</sub>`;
+            const commentBody = [
+              '## 🚀 Preview Deployment Ready',
+              '',
+              "Your preview environment has been deployed to Cloudflare Containers with the PR's Docker image.",
+              '',
+              `**Preview URL:** ${previewUrl}`,
+              '',
+              '> ⏰ This preview is intended to be cleaned up after **24 hours** of the last deployment once the cleanup workflow is live on the default branch.',
+              '> 💤 The container will sleep after 30 minutes of inactivity and wake on the next request.',
+              '',
+              '---',
+              `<sub>Deployed from commit ${headSha}</sub>`,
+            ].join('\n');
 
             // Find existing comment
             const { data: comments } = await github.rest.issues.listComments({
@@ -349,11 +471,3 @@ jobs:
                 body: commentBody
               });
             }
-
-      - name: Store cleanup metadata
-        if: success()
-        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
-        with:
-          name: preview-cleanup-pr-${{ env.PR_NUMBER }}
-          path: ${{ runner.temp }}/sure-preview-worker/wrangler.toml
-          retention-days: 2