fix(ci): preview cleanup no longer fails on GitHub environment delete

.github/workflows/preview.yml

@@ -561,6 +561,10 @@ jobs:
           INPUT_TARGET: ${{ inputs.target }}
           INPUT_PR_NUMBER: ${{ inputs.pr_number }}
         with:
+          # The default GITHUB_TOKEN cannot delete deployment environments (403).
+          # Optional: set repo secret PREVIEW_ENV_CLEANUP_TOKEN to a PAT with repo
+          # scope (classic) or Administration: write (fine-grained) for this repo.
+          github-token: ${{ secrets.PREVIEW_ENV_CLEANUP_TOKEN || github.token }}
           script: |
             const eventName = process.env.EVENT_NAME;
             let envName;
@@ -606,6 +610,14 @@ jobs:
                 core.info(
                   `GitHub environment not found (already deleted): ${envName}`,
                 );
+              } else if (e.status === 403) {
+                core.warning(
+                  [
+                    `Cannot delete GitHub environment "${envName}" with the current token (403).`,
+                    "The current token may not have permission to delete environments.",
+                    "If you're using the default workflow token, add repository secret PREVIEW_ENV_CLEANUP_TOKEN (PAT: classic `repo`, or fine-grained with Administration read/write on this repository). If you're already using a PAT, ensure it has the required permissions.",
+                  ].join(" "),
+                );
               } else {
                 throw e;
               }

docs/agents/setup.md

@@ -121,6 +121,16 @@ each PR preview is isolated:
 When a PR is closed, the cleanup job deletes the preview Worker(s) and these
 resources as well.
 
+The same cleanup job removes the matching GitHub deployment environment
+(`preview-<pr>`). GitHub’s default `GITHUB_TOKEN` cannot call the delete
+environment API (you would see HTTP 403). That step is non-fatal: the workflow
+still succeeds and Cloudflare resources are still removed. To delete the GitHub
+environment automatically, add an Actions secret named
+`PREVIEW_ENV_CLEANUP_TOKEN` whose value is a personal access token with
+permission to administer this repository (for example a classic PAT with the
+`repo` scope, or a fine-grained PAT with **Administration** read and write on
+this repo only).
+
 Cloudflare Workers supports version `preview_urls`, but those preview URLs are
 not currently available for Workers that use Durable Objects. The main app
 Worker binds `MCP_OBJECT`, so app previews continue to use per-PR Worker names.