fix(delivery): expose and retire pull request previews

- attach preview deployments to the pull request head and surface the stable branch alias
- allow manual retirement of a closed pull request without reopening it
- keep immutable Cloudflare deployments as implementation history

Author: xiaoland

.github/workflows/pages-preview-cleanup.yml

@@ -6,27 +6,63 @@ on:
       - main
     types:
       - closed
+  workflow_dispatch:
+    inputs:
+      pull_number:
+        description: Closed pull request whose preview should be retired
+        required: true
+        type: number
 
 permissions:
   contents: read
+  pull-requests: read
 
 concurrency:
-  group: pages-preview-docs-${{ github.event.pull_request.number }}
+  group: pages-preview-docs-${{ github.event.pull_request.number || inputs.pull_number }}
   cancel-in-progress: true
 
 jobs:
   cleanup:
     name: Retire exact pull-request preview
     if: >-
-      github.event.pull_request.base.ref == 'main' &&
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.base.ref == 'main' &&
       github.event.pull_request.base.repo.full_name == github.repository &&
-      github.event.pull_request.head.repo.full_name == github.repository
+      github.event.pull_request.head.repo.full_name == github.repository)
     runs-on: ubuntu-latest
     timeout-minutes: 10
     environment:
       name: preview
-      url: ${{ steps.tombstone.outputs.deployment-url }}
+      url: ${{ steps.tombstone.outputs.pages-deployment-alias-url }}
     steps:
+      - name: Resolve the closed pull request
+        id: identity
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          REQUESTED_PULL_NUMBER: ${{ github.event.pull_request.number || inputs.pull_number }}
+        with:
+          script: |
+            const pullNumber = Number(process.env.REQUESTED_PULL_NUMBER)
+            if (!Number.isInteger(pullNumber) || pullNumber < 1) {
+              core.setFailed('A positive pull-request number is required.')
+              return
+            }
+            const { data: pull } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pullNumber,
+            })
+            if (
+              pull.state !== 'closed' ||
+              pull.base.ref !== 'main' ||
+              pull.base.repo.full_name !== `${context.repo.owner}/${context.repo.repo}` ||
+              pull.head.repo?.full_name !== `${context.repo.owner}/${context.repo.repo}`
+            ) {
+              core.setFailed('Cleanup only accepts a closed same-repository pull request targeting main.')
+              return
+            }
+            core.setOutput('branch', `preview/docs/pr-${pullNumber}`)
+
       - name: Checkout the trusted cleanup controller
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -51,6 +87,6 @@ jobs:
           command: >-
             pages deploy .
             --project-name=${{ vars.CLOUDFLARE_PAGES_PROJECT }}
-            --branch=preview/docs/pr-${{ github.event.pull_request.number }}
+            --branch=${{ steps.identity.outputs.branch }}
             --commit-hash=${{ github.workflow_sha }}
             --commit-dirty=false

.github/workflows/pages-preview.yml

@@ -84,9 +84,6 @@ jobs:
       pull-requests: read
     runs-on: ubuntu-latest
     timeout-minutes: 15
-    environment:
-      name: preview
-      url: ${{ steps.pages.outputs.deployment-url }}
     steps:
       - name: Checkout the trusted preview controller
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -135,6 +132,34 @@ jobs:
               core.setFailed('Pull-request identity changed after artifact selection.')
             }
 
+      - name: Register the pull-request deployment
+        id: github-deployment
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PREVIEW_HEAD_SHA: ${{ needs.identity.outputs.head_sha }}
+          PULL_NUMBER: ${{ needs.identity.outputs.pull_number }}
+        with:
+          script: |
+            const { data: deployment } = await github.rest.repos.createDeployment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: process.env.PREVIEW_HEAD_SHA,
+              environment: 'preview',
+              description: `Cloudflare Pages preview for PR #${process.env.PULL_NUMBER}`,
+              auto_merge: false,
+              required_contexts: [],
+              transient_environment: true,
+              production_environment: false,
+            })
+            core.setOutput('deployment_id', String(deployment.id))
+            await github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: deployment.id,
+              state: 'in_progress',
+              log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            })
+
       - name: Deploy to the isolated Pages preview branch
         id: pages
         uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
@@ -155,5 +180,27 @@ jobs:
         run: node controller/website/scripts/verify-pages-deployment.mjs
         env:
           CLOUDFLARE_PAGES_DEPLOYMENT_ID: ${{ steps.pages.outputs.pages-deployment-id }}
-          CLOUDFLARE_PAGES_DEPLOYMENT_URL: ${{ steps.pages.outputs.deployment-url }}
+          CLOUDFLARE_PAGES_DEPLOYMENT_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }}
           INKCRE_PAGES_SMOKE_MODE: preview
+
+      - name: Report the pull-request deployment
+        if: ${{ always() && steps.github-deployment.outputs.deployment_id != '' }}
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          DEPLOYMENT_ID: ${{ steps.github-deployment.outputs.deployment_id }}
+          JOB_STATUS: ${{ job.status }}
+          PREVIEW_URL: ${{ steps.pages.outputs.pages-deployment-alias-url }}
+        with:
+          script: |
+            const success = process.env.JOB_STATUS === 'success'
+            await github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: Number(process.env.DEPLOYMENT_ID),
+              state: success ? 'success' : 'failure',
+              description: success ? 'Pull-request preview is ready' : 'Pull-request preview failed',
+              log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              ...(success && process.env.PREVIEW_URL
+                ? { environment_url: process.env.PREVIEW_URL }
+                : {}),
+            })

website/README.md

@@ -69,8 +69,10 @@ neither the canonical production artifact nor production delivery. A successful
 request may hand its checked artifact to a trusted controller for an isolated, deterministic,
 short-lived preview. Fork pull requests receive no preview credentials, preview origins remain
 `noindex`, and closing the pull request replaces the live preview with a trusted closed-preview
-tombstone. Cloudflare retains prior immutable deployments in its history. A preview artifact is
-never promoted to production.
+tombstone. The stable `preview-docs-pr-N` branch alias is the user-facing preview URL and is
+recorded against the pull-request head in GitHub; Cloudflare retains the underlying immutable
+deployments in its history. If automatic retirement fails, the cleanup workflow can be run manually
+for the closed pull-request number. A preview artifact is never promoted to production.
 
 Protected `main` is the publication authority. `Pages deployment` runs for a push to `main`; failed
 runs can be rerun for the same commit, while rollback starts by reverting `main` through a pull

website/scripts/verify-pages-deployment.mjs

@@ -159,7 +159,9 @@ if (process.env.GITHUB_STEP_SUMMARY) {
       '## Cloudflare Pages deployment',
       '',
       `- Deployment ID: \`${deploymentId}\``,
-      `- Immutable URL: ${pagesOrigin.origin}`,
+      smokeMode === 'production'
+        ? `- Immutable release URL: ${pagesOrigin.origin}`
+        : `- Pull-request preview URL: ${pagesOrigin.origin}`,
       smokeMode === 'production'
         ? `- Canonical URL: ${canonicalOrigin.origin}`
         : '- Canonical production origin: not contacted by preview validation',