fix(ci): cleanup-pr-preview workflow not firing on PR close

[isuttell]

Why

PR #2 added permissions: administration: write to the cleanup workflow, but administration is not a valid GITHUB_TOKEN scope (only fine-grained PATs accept it). GitHub silently rejected the workflow at evaluation time, dropping every pull_request.closed event for PRs #2--#9 and accumulating 8 stale preview/pr-N Neon branches that tripped the 10-branch free-tier cap (blocked PR #10/#11/#12 deploys with HTTP 422).

Diagnosis

Three signals confirmed the workflow record was wedged:

1. gh api repos/zaks-io/agent-paste/actions/workflows/281097778 returned "name": ".github/workflows/cleanup-pr-preview.yml" (the path), not "Cleanup PR Preview" from the YAML name: field. Other workflows returned their YAML name correctly.
2. gh api '.../actions/runs?per_page=100' --paginate showed exactly one event=pull_request run (PR feat(apex): add marketing worker at agent-paste.sh #1 close, before PR ci(pr-preview): register dynamic GitHub deployment per PR #2 introduced the invalid permission) and 38 event=push startup_failures.
3. GitHub Actions docs enumerate the valid GITHUB_TOKEN permission keys; administration is not in the list.

Changes

• .github/workflows/cleanup-pr-preview.yml → .github/workflows/pr-preview-cleanup.yml (rename forces GitHub to register a fresh workflow id; the old record is wedged and will keep ignoring close events even after the YAML is fixed).
• Drop permissions: administration: write and the deleteAnEnvironment step that needed it. Per-PR pr-preview-N environments are cheap; operator can purge from the UI if desired.
• Validate the resolved PR number is a positive integer before any deletion step runs.
• docs/ops/first-deploy.md: update workflow filename reference.
• docs/ops/project-status.md: flip "PR cleanup workflow" row to "Re-registered" and add a Recently Completed entry capturing root cause + operator follow-up.
• .gitignore: add .agent-out/ so coderabbit artifacts stay local.

Risk

• Low. The cleanup workflow could not have been deleting anything for PRs ci(pr-preview): register dynamic GitHub deployment per PR #2--fix(api,upload): replay idempotent mutations before rate-limit accounting #9 (it never ran), so removing the broken env-deletion step changes nothing observable in production.
• The rename means the GitHub Actions UI loses the old run history under the old filename; the 38 startup_failures and the one PR-feat(apex): add marketing worker at agent-paste.sh #1 run will still be visible under their old workflow id, just not linked from the new file.

Test plan

• pnpm verify green locally (49/49 turbo tasks, Node 24.15.0).
• CodeRabbit review run (coderabbit review --agent --base main); see disposition below.
• Live validation deferred to the next real PR close -- coordinator forbade dispatching against stale PRs ci(pr-preview): register dynamic GitHub deployment per PR #2--fix(api,upload): replay idempotent mutations before rate-limit accounting #9 (would call neondatabase/delete-branch-action@v3 which is exactly the autonomous Neon delete that is gated on Isaac's approval). Once PR feat(api,upload,content): add X-Request-Id and request_id to envelope #10/chore(branches): close obsolete t3code branches #11/docs(ops): add Logpush -> Axiom runbook for click-ops #12 merges, the new workflow id should register and fire on close; check gh api repos/zaks-io/agent-paste/actions/workflows for a NEW workflow id with name: "PR Preview Cleanup".
• Operator follow-up: purge stale preview/pr-2 through preview/pr-9 Neon branches via console.

CodeRabbit findings

1. Minor, .agent-out/cleanup-fix-cr.json:2 -- trailing newline. Skipped: generated artifact, not committed (now gitignored).
2. Major, .agent-out/cleanup-fix-cr.json:1 -- artifact should not be tracked. Accepted: added .agent-out/ to .gitignore.
3. Trivial, .github/workflows/pr-preview-cleanup.yml:52-59 -- PR number lacks validation. Accepted: added ^[1-9][0-9]*$ regex check in Resolve PR number.
4. Critical, .github/workflows/pr-preview-cleanup.yml:13-16 -- administration: write is not a valid permission. Accepted: this was the actual root cause; removed the key and the step that required it.

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Fixed PR preview cleanup workflow to resolve permission validation errors and ensure proper execution during PR closure.
  • Updated cleanup behavior to preserve the GitHub Preview environment while cleaning up related infrastructure.

• Documentation

  • Updated documentation to reference the corrected PR preview cleanup workflow and reflect current cleanup behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4f8fd29e-c09c-4fef-a0a3-db50fdf10ae0

📥 Commits

Reviewing files that changed from the base of the PR and between 8bff59e and 2a3ec50.

📒 Files selected for processing (3)

• .github/workflows/pr-preview-cleanup.yml
• docs/ops/first-deploy.md
• docs/ops/project-status.md

---

Walkthrough

The PR fixes a GitHub Actions workflow authorization failure by renaming the PR preview cleanup workflow and removing an invalid administration: write permissions scope that caused evaluation to fail. The workflow now validates the resolved PR number matches a positive-integer pattern before exporting it. The GitHub Preview environment deletion step was removed since it required the invalid permission. Documentation references to the workflow filename were updated, and the fix is recorded in the project status log with notes on required manual cleanup of stale Neon preview branches.

Possibly related PRs

• zaks-io/agent-paste#2: Directly related—the main PR removes the GitHub Preview environment deletion step in the PR cleanup workflow, adjusting the same cleanup logic.

Poem

A workflow once broken, permissions askew,
With administration: write that GitHub never knew,
We renamed and fixed it with validation so strong,
Now cleanup runs smooth—no more fails along,
The preview stays put, like a rabbit's burrow—home! 🐰

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the main change: fixing a CI workflow that was not firing on PR close due to an invalid permissions scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-agent-a6e5d07f38a0f78ff

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.github/workflows/pr-preview-cleanup.yml (1)

70-81: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Ensure Neon cleanup still runs when Cloudflare cleanup fails.

On Line 75, Neon cleanup is currently skipped if Line 73 fails, because step execution stops on failure unless if: always() is set. That can leave stale preview/pr-* branches behind again.

Suggested fix

       - name: Delete Neon PR branch
+        if: ${{ always() && steps.pr.outputs.number != '' }}
         uses: neondatabase/delete-branch-action@v3
         continue-on-error: true
         with:
           project_id: ${{ vars.NEON_PROJECT_ID }}
           branch: preview/pr-${{ steps.pr.outputs.number }}
           api_key: ${{ secrets.NEON_API_KEY }}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/pr-preview-cleanup.yml around lines 70 - 81, The "Delete
Neon PR branch" step currently depends on normal success of previous steps and
will be skipped if the "Delete Cloudflare PR resources" step fails; update the
"Delete Neon PR branch" job step (named "Delete Neon PR branch") to include an
execution condition so it always runs regardless of earlier failures—add if:
always() to that step so Neon branch cleanup runs even when the Cloudflare
cleanup node script fails.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In @.github/workflows/pr-preview-cleanup.yml:
- Around line 70-81: The "Delete Neon PR branch" step currently depends on
normal success of previous steps and will be skipped if the "Delete Cloudflare
PR resources" step fails; update the "Delete Neon PR branch" job step (named
"Delete Neon PR branch") to include an execution condition so it always runs
regardless of earlier failures—add if: always() to that step so Neon branch
cleanup runs even when the Cloudflare cleanup node script fails.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d843b8f4-10b1-47d0-a2d9-41cf2cc4d3c4

📥 Commits

Reviewing files that changed from the base of the PR and between 82579a7 and 8bff59e.

📒 Files selected for processing (4)

• .github/workflows/pr-preview-cleanup.yml
• .gitignore
• docs/ops/first-deploy.md
• docs/ops/project-status.md

[github-actions]

agent-paste PR preview resources were cleaned up. The pr-preview-${context.issue.number} environment is left in place; remove it from the GitHub UI if desired.