ci(preview): split PR image builds from trusted deploys (#2057)

* ci(preview): split PR image builds from trusted deploys

* ci(preview): harden preview artifact handoff

Move the preview image artifact into the trusted preview workflow as a no-secret build job, gate deployment on base-trusted workflow definitions, and keep Cloudflare credentials isolated to the deploy-only job.

Also fail closed when the pushed image reference is not written into wrangler.toml and expand the preview deploy guard to enforce the same-run artifact and permission boundaries.

* ci(preview): move preview builds out of privileged trigger

* ci(preview): avoid secret-shaped wrangler env assignments

* ci(preview): keep wrangler credential env explicit

.github/workflows/pr.yml

@@ -2,9 +2,60 @@ name: Pull Request
 
 on:
   pull_request:
+    types: [opened, synchronize, reopened, labeled]
     paths-ignore:
       - 'charts/**'
 
+permissions:
+  contents: read
+
 jobs:
   ci:
-    uses: ./.github/workflows/ci.yml
+    uses: ./.github/workflows/ci.yml
+
+  preview_image:
+    needs: ci
+    if: |
+      contains(github.event.pull_request.labels.*.name, 'preview-cf') &&
+      (github.event.action != 'labeled' || github.event.label.name == 'preview-cf')
+    name: Build Cloudflare preview image
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    env:
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      IMAGE_TAG: sure-preview-pr-${{ github.event.pull_request.number }}:${{ github.event.pull_request.head.sha }}
+    steps:
+      - name: Checkout PR code
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+
+      - name: Build preview image without secrets
+        run: |
+          set -euo pipefail
+
+          image_archive="$RUNNER_TEMP/sure-preview-image.tar.gz"
+
+          docker build \
+            --platform linux/amd64 \
+            --build-arg "BUILD_COMMIT_SHA=${HEAD_SHA}" \
+            -f Dockerfile.preview \
+            -t "${IMAGE_TAG}" \
+            .
+
+          docker image inspect "${IMAGE_TAG}" >/dev/null
+          docker save "${IMAGE_TAG}" | gzip -1 > "$image_archive"
+          sha256sum "$image_archive" | awk '{print $1}' > "$RUNNER_TEMP/sure-preview-image.sha256"
+
+      - name: Upload preview image artifact
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: preview-image-pr-${{ env.PR_NUMBER }}-${{ env.HEAD_SHA }}
+          path: |
+            ${{ runner.temp }}/sure-preview-image.tar.gz
+            ${{ runner.temp }}/sure-preview-image.sha256
+          if-no-files-found: error
+          retention-days: 3

.github/workflows/preview-deploy.yml

@@ -1,93 +1,157 @@
 name: Deploy PR Preview
 
 on:
-  pull_request:
-    types: [opened, synchronize, reopened, labeled]
-    paths-ignore:
-      - 'charts/**'
-      - 'docs/**'
-      - '*.md'
+  workflow_run:
+    workflows: ["Pull Request"]
+    types: [completed]
+
+permissions:
+  contents: read
 
 jobs:
-  deploy-preview:
+  preview-gate:
     if: |
-      contains(github.event.pull_request.labels.*.name, 'preview-cf') &&
-      (github.event.action != 'labeled' || github.event.label.name == 'preview-cf')
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    name: Validate preview deployment gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: read
+    outputs:
+      artifact_name: ${{ steps.preview.outputs.artifact_name }}
+      head_sha: ${{ steps.preview.outputs.head_sha }}
+      pr_number: ${{ steps.preview.outputs.pr_number }}
+      should_deploy: ${{ steps.preview.outputs.should_deploy }}
+
+    steps:
+      - 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];
+
+            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:
+    needs: preview-gate
+    if: needs.preview-gate.outputs.should_deploy == 'true'
     name: Deploy to Cloudflare Containers
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 45
     concurrency:
-      group: preview-deploy-${{ github.event.pull_request.number }}
+      group: preview-deploy-${{ needs.preview-gate.outputs.pr_number }}
       cancel-in-progress: true
-    environment:
-      name: preview
+    environment: preview
     permissions:
       actions: read
       contents: read
       pull-requests: write
       deployments: write
     env:
-      PR_NUMBER: ${{ github.event.pull_request.number }}
-      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      ARTIFACT_NAME: ${{ needs.preview-gate.outputs.artifact_name }}
+      HEAD_SHA: ${{ needs.preview-gate.outputs.head_sha }}
+      PR_NUMBER: ${{ needs.preview-gate.outputs.pr_number }}
 
     steps:
-      - name: Wait for PR CI to pass
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
-        with:
-          script: |
-            const headSha = process.env.HEAD_SHA;
-            const timeoutMs = 10 * 60 * 1000;
-            const pollMs = 15 * 1000;
-            const startedAt = Date.now();
-            let lastState = 'not found';
-
-            const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-            while (Date.now() - startedAt < timeoutMs) {
-              const { data } = await github.rest.actions.listWorkflowRunsForRepo({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                event: 'pull_request',
-                head_sha: headSha,
-                per_page: 20,
-              });
-
-              const prRun = data.workflow_runs.find((run) => run.name === 'Pull Request' && run.head_sha === headSha);
-
-              if (prRun) {
-                lastState = `${prRun.status}/${prRun.conclusion ?? 'pending'}`;
-                core.info(`Pull Request workflow ${prRun.id}: ${lastState}`);
-
-                if (prRun.status === 'completed') {
-                  if (prRun.conclusion === 'success') {
-                    return;
-                  }
-
-                  core.setFailed(`Pull Request workflow concluded with ${prRun.conclusion}`);
-                  return;
-                }
-              }
-
-              await sleep(pollMs);
-            }
-
-            core.setFailed(`Timed out waiting for Pull Request workflow for ${headSha}. Last state: ${lastState}`);
-
-      - name: Checkout PR code
-        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          path: pr
-          persist-credentials: false
-
       - name: Checkout trusted preview tooling
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
         with:
-          ref: ${{ github.event.pull_request.base.sha }}
+          ref: ${{ github.event.repository.default_branch }}
           path: trusted
           persist-credentials: false
           sparse-checkout: |
             workers/preview
 
+      - name: Download preview image artifact
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: ${{ env.ARTIFACT_NAME }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+          path: ${{ runner.temp }}/preview-image
+
+      - 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"
+
+          test -f "$image_archive"
+          test -f "$checksum_file"
+
+          expected_checksum="$(tr -d '[:space:]' < "$checksum_file")"
+          actual_checksum="$(sha256sum "$image_archive" | awk '{print $1}')"
+
+          if [ "$expected_checksum" != "$actual_checksum" ]; then
+            echo "Preview image artifact checksum mismatch" >&2
+            exit 1
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
@@ -105,18 +169,76 @@ jobs:
           cp trusted/workers/preview/package-lock.json "$preview_dir/package-lock.json"
           cp trusted/workers/preview/tsconfig.json "$preview_dir/tsconfig.json"
           cp trusted/workers/preview/wrangler.toml "$preview_dir/wrangler.toml"
-          cp -R pr/workers/preview/src "$preview_dir/src"
+          cp -R trusted/workers/preview/src "$preview_dir/src"
 
           sed -i "s/\${PR_NUMBER}/${PR_NUMBER}/g" "$preview_dir/wrangler.toml"
           sed -i "s/\${PR_NUMBER}/${PR_NUMBER}/g" "$preview_dir/src/index.ts"
-          sed -i \
-            "s#image = \"../../Dockerfile.preview\"#image = \"${GITHUB_WORKSPACE}/pr/Dockerfile.preview\"#" \
-            "$preview_dir/wrangler.toml"
 
-          cat "$preview_dir/wrangler.toml"
           cd "$preview_dir"
           npm ci --ignore-scripts --no-audit --no-fund
 
+      - name: Load preview image artifact
+        run: |
+          set -euo pipefail
+
+          image_archive="$RUNNER_TEMP/preview-image/sure-preview-image.tar.gz"
+          expected_image="sure-preview-pr-${PR_NUMBER}:${HEAD_SHA}"
+
+          gzip -dc "$image_archive" | docker load
+          docker image inspect "$expected_image" >/dev/null
+
+      - name: Push preview image to Cloudflare registry
+        id: image
+        env:
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_PREVIEW_API_TOKEN || secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          cd "$RUNNER_TEMP/sure-preview-worker"
+          image_tag="sure-preview-pr-${PR_NUMBER}:${HEAD_SHA}"
+          push_log="$RUNNER_TEMP/wrangler-containers-push.log"
+          clean_log="$RUNNER_TEMP/wrangler-containers-push.clean.log"
+
+          ./node_modules/.bin/wrangler containers push "$image_tag" 2>&1 | tee "$push_log"
+          perl -pe 's/\e\[[0-9;]*[A-Za-z]//g' "$push_log" > "$clean_log"
+          image_ref=$(grep -Eo 'registry\.cloudflare\.com/[^[:space:]]+' "$clean_log" | tail -n 1 | tr -d '\r')
+
+          if [ -z "$image_ref" ]; then
+            echo "Could not find Cloudflare registry image reference in wrangler output" >&2
+            exit 1
+          fi
+
+          echo "image_ref=${image_ref}" >> "$GITHUB_OUTPUT"
+
+      - name: Configure trusted preview image reference
+        env:
+          IMAGE_REF: ${{ steps.image.outputs.image_ref }}
+        run: |
+          set -euo pipefail
+
+          config_path="$RUNNER_TEMP/sure-preview-worker/wrangler.toml"
+          # Use Node instead of sed so the replacement preserves TOML string syntax.
+          node - "$config_path" <<'NODE'
+          const fs = require('node:fs');
+
+          const configPath = process.argv[2];
+          const imageRef = process.env.IMAGE_REF;
+
+          if (!imageRef || !imageRef.startsWith('registry.cloudflare.com/')) {
+            throw new Error('Expected a Cloudflare registry image reference');
+          }
+
+          const original = fs.readFileSync(configPath, 'utf8');
+          const updated = original.replace(/image = "[^"]+"/, `image = ${JSON.stringify(imageRef)}`);
+          if (updated === original) {
+            throw new Error('Expected wrangler.toml to contain an image entry to rewrite');
+          }
+          fs.writeFileSync(configPath, updated);
+          NODE
+
+          cat "$config_path"
+
       - name: Create GitHub Deployment
         id: deployment
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
@@ -139,8 +261,8 @@ jobs:
       - name: Deploy to Cloudflare Containers
         id: deploy
         env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_PREVIEW_API_TOKEN || secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_WORKERS_SUBDOMAIN: ${{ secrets.CLOUDFLARE_WORKERS_SUBDOMAIN }}
         run: |
           set -euo pipefail
@@ -227,6 +349,7 @@ jobs:
                 body: commentBody
               });
             }
+
       - name: Store cleanup metadata
         if: success()
         uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6

bin/preview_deploy_security_check.rb

@@ -4,9 +4,17 @@
 %w[json pathname yaml].each { |library| require library }
 
 ROOT = File.expand_path("..", __dir__)
-WORKFLOW_PATH = File.join(ROOT, ".github/workflows/preview-deploy.yml")
+PREVIEW_WORKFLOW_PATH = File.join(ROOT, ".github/workflows/preview-deploy.yml")
+PR_WORKFLOW_PATH = File.join(ROOT, ".github/workflows/pr.yml")
 LOCKFILE_PATH = File.join(ROOT, "workers/preview/package-lock.json")
 PINNED_ACTION = /\A[^@\s]+@[a-f0-9]{40}\z/
+EXPECTED_ACTION_PINS = {
+  "actions/checkout" => "93cb6efe18208431cddfb8368fd83d5badbf9bfd", # v5
+  "actions/download-artifact" => "018cc2cf5baa6db3ef3c5f8a56943fffe632ef53", # v6
+  "actions/github-script" => "f28e40c7f34bde8b3046d885e986cb6290c5673b", # v7
+  "actions/setup-node" => "48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e", # v6
+  "actions/upload-artifact" => "b7c566a772e6b6bfb58ed0dc250532a479d7789f" # v6
+}.freeze
 INLINE_SECRET_EXPRESSION = /\$\{\{\s*secrets\s*(?:\.|\[)/i
 INLINE_PR_EXPRESSION = /
   \$\{\{\s*
@@ -23,17 +31,34 @@ GITHUB_WORKSPACE_PREFIX = %r{
   )
   (?:/|\z)
 }ix
-EXPECTED_PERMISSIONS = { "actions" => "read", "contents" => "read", "pull-requests" => "write", "deployments" => "write" }.freeze
-EXPECTED_SECRET_ENV = %w[CLOUDFLARE_ACCOUNT_ID CLOUDFLARE_API_TOKEN CLOUDFLARE_WORKERS_SUBDOMAIN].freeze
+EXPECTED_TOP_LEVEL_PERMISSIONS = { "contents" => "read" }.freeze
+EXPECTED_GATE_PERMISSIONS = { "actions" => "read", "contents" => "read", "pull-requests" => "read" }.freeze
+EXPECTED_IMAGE_PERMISSIONS = { "contents" => "read" }.freeze
+EXPECTED_DEPLOY_PERMISSIONS = {
+  "actions" => "read",
+  "contents" => "read",
+  "deployments" => "write",
+  "pull-requests" => "write"
+}.freeze
+EXPECTED_DEPLOY_SECRET_ENV = %w[CLOUDFLARE_ACCOUNT_ID CLOUDFLARE_API_TOKEN CLOUDFLARE_WORKERS_SUBDOMAIN].freeze
+EXPECTED_PUSH_SECRET_ENV = %w[CLOUDFLARE_ACCOUNT_ID CLOUDFLARE_API_TOKEN].freeze
 REQUIRED_PREPARE_LINES = [
   'cp trusted/workers/preview/package.json "$preview_dir/package.json"',
   'cp trusted/workers/preview/package-lock.json "$preview_dir/package-lock.json"',
   'cp trusted/workers/preview/tsconfig.json "$preview_dir/tsconfig.json"',
   'cp trusted/workers/preview/wrangler.toml "$preview_dir/wrangler.toml"',
-  'cp -R pr/workers/preview/src "$preview_dir/src"',
-  'image = \"${GITHUB_WORKSPACE}/pr/Dockerfile.preview\"',
+  'cp -R trusted/workers/preview/src "$preview_dir/src"',
   "npm ci --ignore-scripts --no-audit --no-fund"
 ].freeze
+REQUIRED_IMAGE_BUILD_LINES = [
+  "docker build",
+  "--platform linux/amd64",
+  '--build-arg "BUILD_COMMIT_SHA=${HEAD_SHA}"',
+  "-f Dockerfile.preview",
+  '-t "${IMAGE_TAG}"',
+  'docker save "${IMAGE_TAG}" | gzip -1 > "$image_archive"',
+  'sha256sum "$image_archive"'
+].freeze
 
 def fail_check(message)
   warn "preview-deploy security check failed: #{message}"
@@ -44,6 +69,10 @@ def assert(value, message)
   fail_check(message) unless value
 end
 
+def workflow_on(workflow)
+  workflow["on"] || workflow[true] || fail_check("workflow is missing on trigger")
+end
+
 def step!(steps, name)
   steps.find { |step| step["name"] == name } || fail_check("missing #{name.inspect} step")
 end
@@ -52,8 +81,16 @@ def run(step)
   step.fetch("run", "")
 end
 
+def step_body(step)
+  [ run(step), step.dig("with", "script") ].compact.join("\n")
+end
+
+def env_hash(node)
+  node.fetch("env", {})
+end
+
 def assert_run_includes(step, *needles)
-  script = run(step)
+  script = step_body(step)
   needles.each { |needle| assert(script.include?(needle), "#{step["name"]} must include #{needle.inspect}") }
   script
 end
@@ -70,67 +107,187 @@ def environment_name(job)
   environment.is_a?(Hash) ? environment["name"] : environment
 end
 
-workflow = YAML.safe_load_file(WORKFLOW_PATH, aliases: true)
+def assert_pinned_actions!(steps)
+  steps.each do |step|
+    uses = step["uses"]
+    next unless uses
+    next if uses.start_with?("./")
+
+    assert(uses.match?(PINNED_ACTION), "#{step["name"] || uses} must pin external actions")
+
+    action, sha = uses.split("@", 2)
+    expected_sha = EXPECTED_ACTION_PINS[action]
+    assert(sha == expected_sha, "#{step["name"] || uses} must pin #{action} to #{expected_sha}") if expected_sha
+  end
+end
+
+def assert_no_inline_expressions!(steps)
+  inline_scripts = steps.flat_map { |step| [ run(step), step.dig("with", "script") ] }.compact.join("\n")
+  assert(!inline_scripts.match?(INLINE_SECRET_EXPRESSION), "secrets must enter scripts through env")
+  assert(!inline_scripts.match?(INLINE_PR_EXPRESSION), "PR fields must enter scripts through env")
+end
+
+def assert_secret_env_sources!(step, expected_keys)
+  env = step.fetch("env")
+
+  assert(env.keys.sort == expected_keys, "#{step["name"]} secret env keys must be #{expected_keys.inspect}")
+  assert(expected_keys.all? { |name| env.fetch(name).start_with?("${{ secrets.") }, "#{step["name"]} secret env must be sourced from GitHub secrets")
+end
+
+preview_workflow = YAML.safe_load_file(PREVIEW_WORKFLOW_PATH, aliases: true)
+pr_workflow = YAML.safe_load_file(PR_WORKFLOW_PATH, aliases: true)
 lockfile = JSON.parse(File.read(LOCKFILE_PATH))
-job = workflow.fetch("jobs").fetch("deploy-preview")
-steps = job.fetch("steps")
-step_names = steps.map { |step| step["name"] }
-pr_checkout = step!(steps, "Checkout PR code")
-trusted_checkout = step!(steps, "Checkout trusted preview tooling")
-prepare = step!(steps, "Prepare trusted preview deploy workspace")
-deploy = step!(steps, "Deploy to Cloudflare Containers")
+
+preview_on = workflow_on(preview_workflow)
+pr_on = workflow_on(pr_workflow)
+preview_jobs = preview_workflow.fetch("jobs")
+pr_jobs = pr_workflow.fetch("jobs")
+gate_job = preview_jobs.fetch("preview-gate")
+image_job = pr_jobs.fetch("preview_image")
+deploy_job = preview_jobs.fetch("deploy-preview")
+gate_steps = gate_job.fetch("steps")
+image_steps = image_job.fetch("steps")
+deploy_steps = deploy_job.fetch("steps")
+deploy_step_names = deploy_steps.map { |step| step["name"] }
 wrangler = lockfile.fetch("packages").fetch("node_modules/wrangler")
 
+resolve_preview = step!(gate_steps, "Resolve preview request")
+
+pr_checkout = step!(image_steps, "Checkout PR code")
+build_image = step!(image_steps, "Build preview image without secrets")
+upload_image = step!(image_steps, "Upload preview image artifact")
+
+trusted_checkout = step!(deploy_steps, "Checkout trusted preview tooling")
+download_artifact = step!(deploy_steps, "Download preview image artifact")
+verify_checksum = step!(deploy_steps, "Verify preview image artifact checksum")
+prepare = step!(deploy_steps, "Prepare trusted preview deploy workspace")
+load_image = step!(deploy_steps, "Load preview image artifact")
+push_image = step!(deploy_steps, "Push preview image to Cloudflare registry")
+configure_image = step!(deploy_steps, "Configure trusted preview image reference")
+deploy = step!(deploy_steps, "Deploy to Cloudflare Containers")
+
 [
-  [ "job permissions", job.fetch("permissions"), EXPECTED_PERMISSIONS ],
-  [ "job environment", environment_name(job), "preview" ],
-  [ "concurrency group", job.dig("concurrency", "group"), "preview-deploy-${{ github.event.pull_request.number }}" ],
-  [ "concurrency cancellation", job.dig("concurrency", "cancel-in-progress"), true ],
-  [ "PR_NUMBER env", job.dig("env", "PR_NUMBER"), "${{ github.event.pull_request.number }}" ],
-  [ "HEAD_SHA env", job.dig("env", "HEAD_SHA"), "${{ github.event.pull_request.head.sha }}" ],
-  [ "PR checkout path", pr_checkout.dig("with", "path"), "pr" ],
+  [ "preview trigger", preview_on.keys, [ "workflow_run" ] ],
+  [ "preview trigger workflows", preview_on.dig("workflow_run", "workflows"), [ "Pull Request" ] ],
+  [ "preview trigger types", preview_on.dig("workflow_run", "types"), [ "completed" ] ],
+  [ "preview top-level permissions", preview_workflow.fetch("permissions"), EXPECTED_TOP_LEVEL_PERMISSIONS ],
+  [ "preview workflow jobs", preview_jobs.keys, [ "preview-gate", "deploy-preview" ] ],
+  [ "PR workflow trigger types", pr_on.dig("pull_request", "types"), %w[opened synchronize reopened labeled] ],
+  [ "PR workflow paths-ignore", pr_on.dig("pull_request", "paths-ignore"), [ "charts/**" ] ],
+  [ "PR workflow permissions", pr_workflow.fetch("permissions"), EXPECTED_TOP_LEVEL_PERMISSIONS ],
+  [ "PR workflow jobs", pr_jobs.keys, [ "ci", "preview_image" ] ],
+  [ "preview gate permissions", gate_job.fetch("permissions"), EXPECTED_GATE_PERMISSIONS ],
+  [ "preview gate timeout", gate_job.fetch("timeout-minutes"), 10 ],
+  [ "preview gate should_deploy output", gate_job.dig("outputs", "should_deploy"), "${{ steps.preview.outputs.should_deploy }}" ],
+  [ "preview gate artifact output", gate_job.dig("outputs", "artifact_name"), "${{ steps.preview.outputs.artifact_name }}" ],
+  [ "preview gate head output", gate_job.dig("outputs", "head_sha"), "${{ steps.preview.outputs.head_sha }}" ],
+  [ "preview gate PR output", gate_job.dig("outputs", "pr_number"), "${{ steps.preview.outputs.pr_number }}" ],
+  [ "preview image needs", image_job.fetch("needs"), "ci" ],
+  [ "preview image permissions", image_job.fetch("permissions"), EXPECTED_IMAGE_PERMISSIONS ],
+  [ "preview image timeout", image_job.fetch("timeout-minutes"), 30 ],
+  [ "image PR_NUMBER env", image_job.dig("env", "PR_NUMBER"), "${{ github.event.pull_request.number }}" ],
+  [ "image HEAD_SHA env", image_job.dig("env", "HEAD_SHA"), "${{ github.event.pull_request.head.sha }}" ],
+  [ "image tag env", image_job.dig("env", "IMAGE_TAG"), "sure-preview-pr-${{ github.event.pull_request.number }}:${{ github.event.pull_request.head.sha }}" ],
+  [ "deploy job needs", deploy_job.fetch("needs"), "preview-gate" ],
+  [ "deploy job permissions", deploy_job.fetch("permissions"), EXPECTED_DEPLOY_PERMISSIONS ],
+  [ "deploy job environment", environment_name(deploy_job), "preview" ],
+  [ "deploy job timeout", deploy_job.fetch("timeout-minutes"), 45 ],
+  [ "deploy concurrency group", deploy_job.dig("concurrency", "group"), "preview-deploy-${{ needs.preview-gate.outputs.pr_number }}" ],
+  [ "deploy concurrency cancellation", deploy_job.dig("concurrency", "cancel-in-progress"), true ],
+  [ "deploy ARTIFACT_NAME env", deploy_job.dig("env", "ARTIFACT_NAME"), "${{ needs.preview-gate.outputs.artifact_name }}" ],
+  [ "deploy HEAD_SHA env", deploy_job.dig("env", "HEAD_SHA"), "${{ needs.preview-gate.outputs.head_sha }}" ],
+  [ "deploy PR_NUMBER env", deploy_job.dig("env", "PR_NUMBER"), "${{ needs.preview-gate.outputs.pr_number }}" ],
   [ "PR checkout credentials", pr_checkout.dig("with", "persist-credentials"), false ],
-  [ "trusted checkout ref", trusted_checkout.dig("with", "ref"), "${{ github.event.pull_request.base.sha }}" ],
+  [ "upload artifact name", upload_image.dig("with", "name"), "preview-image-pr-${{ env.PR_NUMBER }}-${{ env.HEAD_SHA }}" ],
+  [ "upload artifact retention", upload_image.dig("with", "retention-days"), 3 ],
+  [ "trusted checkout ref", trusted_checkout.dig("with", "ref"), "${{ github.event.repository.default_branch }}" ],
   [ "trusted checkout path", trusted_checkout.dig("with", "path"), "trusted" ],
   [ "trusted checkout credentials", trusted_checkout.dig("with", "persist-credentials"), false ],
-  [ "deploy secret env", deploy.fetch("env").keys.sort, EXPECTED_SECRET_ENV ],
+  [ "download artifact name", download_artifact.dig("with", "name"), "${{ env.ARTIFACT_NAME }}" ],
+  [ "download artifact run id", download_artifact.dig("with", "run-id"), "${{ github.event.workflow_run.id }}" ],
+  [ "download artifact token", download_artifact.dig("with", "github-token"), "${{ github.token }}" ],
+  [ "download artifact path", download_artifact.dig("with", "path"), "${{ runner.temp }}/preview-image" ],
   [ "Wrangler binary", wrangler.dig("bin", "wrangler"), "bin/wrangler.js" ]
 ].each { |label, actual, expected| assert(actual == expected, "#{label}: expected #{actual.inspect} to equal #{expected.inspect}") }
 
+assert(pr_on.key?("pull_request"), "PR workflow must still run on pull_request")
+assert(!preview_on.key?("pull_request_target"), "privileged preview deploy workflow must not run on pull_request_target")
+assert(!preview_on.key?("pull_request"), "privileged preview deploy workflow must not run directly on pull_request")
+assert(gate_job.fetch("if").include?("github.event.workflow_run.event == 'pull_request'"), "preview gate must only accept pull_request workflow runs")
+assert(gate_job.fetch("if").include?("github.event.workflow_run.conclusion == 'success'"), "preview gate must only accept successful PR workflow runs")
+assert(image_job.fetch("if").include?("preview-cf"), "preview image build must stay gated by preview-cf")
+assert(deploy_job.fetch("if") == "needs.preview-gate.outputs.should_deploy == 'true'", "privileged preview deploy must depend on the gate output")
+assert(gate_job["environment"].nil?, "preview gate must not use a protected secret-bearing environment")
+assert(image_job["environment"].nil?, "preview image build must not use a protected secret-bearing environment")
 assert(lockfile.dig("packages", "", "devDependencies", "wrangler"), "Wrangler must stay a root dev dependency")
 assert(lockfile.fetch("lockfileVersion") >= 3, "preview tooling lockfile must preserve npm ci integrity metadata")
 assert(wrangler.fetch("resolved").start_with?("https://registry.npmjs.org/wrangler/-/wrangler-"), "Wrangler must resolve from npm registry")
 assert(wrangler.fetch("integrity").start_with?("sha512-"), "Wrangler lockfile entry must keep npm integrity metadata")
 assert(trusted_checkout.dig("with", "sparse-checkout").to_s.include?("workers/preview"), "trusted checkout must include preview tooling")
-assert(step_names.compact.uniq == step_names.compact, "workflow step names must stay unique for security checks")
-assert([ pr_checkout, trusted_checkout, prepare, deploy ].map { |step| steps.index(step) }.each_cons(2).all? { |left, right| left < right }, "checkout, preparation, and deploy steps must stay ordered")
-assert(job.fetch("env").keys.none? { |name| name.start_with?("CLOUDFLARE_") }, "Cloudflare secrets must not be job-wide")
-assert(EXPECTED_SECRET_ENV.all? { |name| deploy.fetch("env").fetch(name).start_with?("${{ secrets.") }, "deploy secret env must be sourced from GitHub secrets")
+assert(deploy_step_names.compact.uniq == deploy_step_names.compact, "workflow step names must stay unique for security checks")
+assert([ trusted_checkout, download_artifact, verify_checksum, prepare, load_image, push_image, configure_image, deploy ].map { |step| deploy_steps.index(step) }.each_cons(2).all? { |left, right| left < right }, "deploy workflow steps must preserve safe cross-run artifact deploy order")
+assert(deploy_steps.none? { |step| step["name"] == "Checkout PR code" }, "privileged deploy job must not checkout PR code")
+assert(env_hash(deploy_job).keys.none? { |name| name.start_with?("CLOUDFLARE_") }, "Cloudflare secrets must not be job-wide")
+assert(env_hash(gate_job).keys.none? { |name| name.start_with?("CLOUDFLARE_") }, "preview gate must not receive Cloudflare secrets")
+assert(env_hash(image_job).keys.none? { |name| name.start_with?("CLOUDFLARE_") }, "preview image build must not receive Cloudflare secrets")
+assert(upload_image.dig("with", "path").to_s.include?("sure-preview-image.tar.gz"), "preview image artifact must include the image archive")
+assert(upload_image.dig("with", "path").to_s.include?("sure-preview-image.sha256"), "preview image artifact must include the checksum")
 
-steps.each do |step|
-  uses = step["uses"]
-  assert(uses.start_with?("./") || uses.match?(PINNED_ACTION), "#{step["name"] || uses} must pin external actions") if uses
-end
+assert_pinned_actions!(gate_steps)
+assert_pinned_actions!(image_steps)
+assert_pinned_actions!(deploy_steps)
+assert_no_inline_expressions!(gate_steps)
+assert_no_inline_expressions!(image_steps)
+assert_no_inline_expressions!(deploy_steps)
 
-inline_scripts = steps.flat_map { |step| [ run(step), step.dig("with", "script") ] }.compact.join("\n")
-assert(!inline_scripts.match?(INLINE_SECRET_EXPRESSION), "secrets must enter scripts through env")
-assert(!inline_scripts.match?(INLINE_PR_EXPRESSION), "PR fields must enter scripts through env")
-assert(steps.none? { |step| normalized_working_directory(step["working-directory"]).match?(PR_CONTROLLED_WORKDIR) }, "steps must not run from PR-controlled dirs")
-assert(steps.none? { |step| run(step).include?("npx wrangler") }, "workflow must not use npx wrangler")
+all_steps = gate_steps + image_steps + deploy_steps
+assert(all_steps.none? { |step| env_hash(step).values.join("\n").match?(INLINE_SECRET_EXPRESSION) && ![ push_image, deploy ].include?(step) }, "only Cloudflare steps may reference GitHub secrets")
+assert(deploy_steps.none? { |step| normalized_working_directory(step["working-directory"]).match?(PR_CONTROLLED_WORKDIR) }, "privileged deploy steps must not run from PR-controlled dirs")
+assert(deploy_steps.none? { |step| run(step).include?("npx wrangler") }, "privileged deploy workflow must not use npx wrangler")
+assert(deploy_steps.none? { |step| run(step).match?(/Dockerfile\.preview|docker build|docker save/) }, "privileged deploy job must not build PR Dockerfiles")
+assert(deploy_steps.none? { |step| run(step).include?("${GITHUB_WORKSPACE}/pr") || run(step).include?(" pr/") }, "privileged deploy job must not reference PR checkout paths")
+assert(image_steps.none? { |step| env_hash(step).keys.any? { |key| key.start_with?("CLOUDFLARE_") } }, "preview image workflow must not expose Cloudflare secret env")
+assert(image_steps.none? { |step| [ run(step), env_hash(step).values.join("\n") ].join("\n").match?(INLINE_SECRET_EXPRESSION) }, "preview image workflow must not reference GitHub secrets")
+
+assert_run_includes(
+  resolve_preview,
+  "context.payload.workflow_run",
+  "workflowRun.pull_requests?.[0]",
+  "github.rest.pulls.get",
+  "pullRequest.head.sha !== headSha",
+  "preview-cf",
+  "github.rest.pulls.listFiles",
+  "filename.startsWith('.github/workflows/')",
+  "github.rest.actions.listWorkflowRunArtifacts",
+  "preview-image-pr-${prNumber}-${headSha}",
+  "!item.expired",
+  "core.setOutput('artifact_name', artifactName)",
+  "core.setOutput('should_deploy', 'true')"
+)
 
 prepare_run = assert_run_includes(prepare, *REQUIRED_PREPARE_LINES)
 assert(!prepare_run.include?("npm install"), "prepare step must not use npm install")
 assert(!prepare_run.include?("CLOUDFLARE_API_TOKEN"), "prepare step must not receive Cloudflare secrets")
-assert([ prepare, deploy ].all? { |step| run(step).include?("set -euo pipefail") }, "trusted setup and deploy scripts must fail closed")
 assert(prepare_run.include?('preview_dir="$RUNNER_TEMP/sure-preview-worker"'), "trusted workspace must be created under RUNNER_TEMP")
-assert(steps.select { |step| run(step).match?(/npm (ci|install)/) }.map { |step| step["name"] } == [ prepare["name"] ], "only prepare may install deploy tooling")
+assert(deploy_steps.select { |step| run(step).match?(/npm (ci|install)/) }.map { |step| step["name"] } == [ prepare["name"] ], "only prepare may install deploy tooling")
 
-secret_steps = steps.select { |step| step.fetch("env", {}).then { |env| env.key?("CLOUDFLARE_API_TOKEN") || env.key?("CLOUDFLARE_ACCOUNT_ID") } }
-assert(secret_steps.map { |step| step["name"] } == [ deploy["name"] ], "only deploy may receive Cloudflare secrets")
+image_build_run = assert_run_includes(build_image, *REQUIRED_IMAGE_BUILD_LINES)
+assert(image_build_run.include?("set -euo pipefail"), "preview image build must fail closed")
+assert(!image_build_run.include?("CLOUDFLARE_"), "preview image build must not receive Cloudflare secrets")
+
+assert_run_includes(verify_checksum, 'expected_checksum="$(tr -d', 'actual_checksum="$(sha256sum "$image_archive"', "Preview image artifact checksum mismatch")
+assert_run_includes(load_image, 'gzip -dc "$image_archive" | docker load', 'docker image inspect "$expected_image"')
+assert_run_includes(push_image, "./node_modules/.bin/wrangler containers push", "registry\\.cloudflare\\.com/", "image_ref=")
+assert_run_includes(configure_image, "imageRef.startsWith('registry.cloudflare.com/')", 'const original = fs.readFileSync', 'const updated = original.replace(/image = "[^"]+"/', "updated === original", "Expected wrangler.toml to contain an image entry to rewrite", "JSON.stringify(imageRef)")
+assert_run_includes(deploy, 'cd "$RUNNER_TEMP/sure-preview-worker"', "./node_modules/.bin/wrangler deploy --config wrangler.toml", '--var "PR_NUMBER:${PR_NUMBER}"')
+
+secret_steps = deploy_steps.select { |step| env_hash(step).then { |env| env.key?("CLOUDFLARE_API_TOKEN") || env.key?("CLOUDFLARE_ACCOUNT_ID") } }
+assert(secret_steps.map { |step| step["name"] } == [ push_image["name"], deploy["name"] ], "only image push and deploy may receive Cloudflare secrets")
+assert_secret_env_sources!(push_image, EXPECTED_PUSH_SECRET_ENV)
+assert_secret_env_sources!(deploy, EXPECTED_DEPLOY_SECRET_ENV)
 secret_steps.each do |step|
   assert(step["working-directory"].nil?, "#{step["name"]} must not run from a PR-controlled working directory")
-  assert(!run(step).match?(/npx wrangler|npm (ci|install)/), "#{step["name"]} must not execute PR-controlled tooling with secrets")
+  assert(!run(step).match?(/npx wrangler|npm (ci|install)|docker build|docker save|docker run/), "#{step["name"]} must not execute PR-controlled build or package tooling with secrets")
 end
 
-assert_run_includes(deploy, 'cd "$RUNNER_TEMP/sure-preview-worker"', "./node_modules/.bin/wrangler deploy --config wrangler.toml", '--var "PR_NUMBER:${PR_NUMBER}"')
 puts "preview-deploy security check passed"