ci(pr-preview): register dynamic GitHub deployment per PR

[isuttell]

Summary

Make GitHub show a Deployments panel on each PR when the PR preview workflow runs. Today the preview deploys to ephemeral *-pr-N Workers but GitHub has no record, so PRs don't surface the URL or status. A dynamic per-PR environment is created on deploy and deleted on PR close, so the environment exists iff the Workers exist.

Changes

• .github/workflows/pr-preview.yml: declare environment: pr-preview-<N> with url: ${{ steps.deploy.outputs.apex_url }} on the deploy job. GitHub auto-creates the env on first run.
• .github/workflows/cleanup-pr-preview.yml: add administration: write to the job permissions and a new step that calls DELETE /repos/{owner}/{repo}/environments/{name} via actions/github-script. 404 is treated as a no-op so cleanups for never-deployed PRs (forks, failed setup) don't fail.

Risk: LOW

• Areas touched: GitHub Actions workflows only. No application code, no migrations.
• Security: cleanup job now requests administration: write on the auto-issued GITHUB_TOKEN. Scope is needed to delete environments; not used for anything else. If org policy denies the elevation, the cleanup step 403s but the workers/Neon branch already deleted before that point.
• Performance: none.
• Breaking: no. Existing Preview environment (empty, manually created) is left in place for a future long-lived preview deploy workflow.

Test plan

• Open this PR — confirm GitHub creates a pr-preview-<this-PR-number> environment, the deploy job runs against it, and the PR sidebar shows a Deployments panel with the apex URL.
• Close the PR — confirm the cleanup workflow runs, deletes the Cloudflare/Neon resources, and removes the pr-preview-<N> environment from gh api repos/zaks-io/agent-paste/environments.
• Re-open the PR — confirm a new environment is created and the cycle works again.

CodeRabbit notes

• Skipped: pin actions/github-script@v8 to a commit SHA. Conflicts with the repo convention of floating major tags across all actions/* actions (see ci.yml, pr-preview.yml, and the existing comment step in this same file).

Summary by CodeRabbit

• Chores

  • Improved PR preview lifecycle: added safer cleanup, explicit preview environment declaration, and post-deploy DNS/availability checks; updated token permissions for these steps.

• Documentation

  • Centralized project status and roadmap into a single ops document (replacing the old bootstrap checklist); added onboarding order guidance and updated MVP spec to reference the new source of truth.

[coderabbitai]

Walkthrough

This PR implements automated cleanup for GitHub Actions PR preview environments and consolidates project status documentation. The pr-preview workflow now tags deployments with named GitHub Actions environments, enabling environment-based deployment protection and tracking. A new cleanup-pr-preview workflow acquires administrative permissions and deletes these per-PR environments when PRs close, gracefully handling missing environments. Concurrently, project-status.md becomes the single source of truth for project roadmap status, implementation state, verified testing results, specification coverage gaps, ADR tracking, and a prioritized fifteen-item backlog. The old mvp-bootstrap-checklist.md is removed, and documentation references are updated to point to the new home.

Sequence Diagram(s)

sequenceDiagram
  participant ComponentA
  participant ComponentB
  ComponentA->>ComponentB: observable interaction

Loading

Possibly related PRs

• zaks-io/agent-paste#1: Also modifies pr-preview.yml to surface the Apex URL and adds preview wait handling related to that endpoint.

Poem

🐰 Environments rise on code's bright wing,

URLs checked until they sing,
When PRs close, the tidy sweep begins,
One doc to read, no scattered bins,
A rabbit hums — deploys end with grins.

🚥 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 accurately describes the primary change: registering a dynamic GitHub deployment environment per PR in the CI/preview workflow. It clearly identifies the main objective and scope of the changeset.
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 t3code/638b75b9

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 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.

Inline comments:
In @.github/workflows/cleanup-pr-preview.yml:
- Line 16: Remove the invalid permission line "administration: write" and
instead mint a GitHub App installation token using the
actions/create-github-app-token@v2 action, then pass that token into the
environment deletion step via the github-token input; update the job to call
create-github-app-token (store its output as e.g. github_app_token) and use that
output in the deleteAnEnvironment call so the repository Administration write
scope is provided by the App token rather than GITHUB_TOKEN.

In `@AGENTS.md`:
- Around line 3-8: Update AGENTS.md to add explicit agent definitions and
configuration fields: for each agent (give them clear identifiers/names),
document role, capabilities, constraints, required inputs and environment
variables, ownership/escalation path, expected outputs, and any runtime/config
flags; derive implemented/partial/deferred status from
docs/ops/project-status.md and cross-reference relevant domain language in
CONTEXT.md and specs in docs/specs/README.md; ensure each agent section uses
consistent field names (e.g., name, role, capabilities, constraints,
required_env, escalation_owner, status) so downstream code can parse these
entries.

In `@docs/ops/project-status.md`:
- Around line 166-236: MD022 errors come from missing blank lines immediately
after level-3 backlog headings; edit the Markdown document and insert a single
blank line after each "###" backlog heading (e.g., "### 1. Wire `runCommand` and
`createOperationEvent` into mutation routes", "### 2. Enforce native rate-limit
bindings", etc.) so every level-3 heading is followed by exactly one empty line
before the next paragraph or list item, then run markdownlint to verify the
MD022 warnings are resolved.
- Line 5: The docs conflict: docs/ops/project-status.md currently states it is
read after CONTEXT.md/specs/ADRs while AGENTS.md says to read project-status.md
first; pick the canonical read order and make the wording consistent across both
files—either change the sentence in project-status.md that begins "First doc a
fresh agent reads after ..." to match AGENTS.md's “read first” phrasing, or
update AGENTS.md to instruct reading it after
CONTEXT.md/docs/specs/README.md/docs/adr/README.md; ensure the doc titles
(project-status.md, AGENTS.md, CONTEXT.md, docs/specs/README.md,
docs/adr/README.md) are referenced consistently and update the single line where
the order is described.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2850c318-c228-4dbf-8073-4a1c777c6785

📥 Commits

Reviewing files that changed from the base of the PR and between 4bde837 and b41136f.

📒 Files selected for processing (6)

• .github/workflows/cleanup-pr-preview.yml
• .github/workflows/pr-preview.yml
• AGENTS.md
• docs/ops/mvp-bootstrap-checklist.md
• docs/ops/project-status.md
• docs/specs/mvp.md

💤 Files with no reviewable changes (1)

• docs/ops/mvp-bootstrap-checklist.md

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

cat -n .github/workflows/cleanup-pr-preview.yml | head -100

Repository: zaks-io/agent-paste

Length of output: 3768

---

🌐 Web query:

GitHub Actions GITHUB_TOKEN workflow permissions available scopes list

💡 Result:

GitHub Actions’ automatically created GITHUB_TOKEN supports these workflow/job “permissions” scopes (parameterized names) that you can set via the permissions: key (values typically read/write/none depending on the scope): actions, checks, contents, deployments, issues, packages, pull-requests, repository-projects, security-events, statuses. [1][2][3] Note: The scopes list is used with the workflow permissions key to grant least privilege; any permission that is absent is set to none. [1] Example: permissions: contents: read packages: read pull-requests: none [1]

Citations:

• 1: https://github.blog/changelog/2021-04-20-github-actions-control-permissions-for-github_token/
• 2: https://docs.github.com/en/enterprise-server@3.0/actions/reference/authentication-in-a-workflow
• 3: https://docs.github.com/actions/concepts/security/github_token

---

🌐 Web query:

GitHub REST API deleteAnEnvironment authorization requirements permissions

💡 Result:

To delete an environment using the GitHub REST API (DELETE /repos/{owner}/{repo}/environments/{environment_name}), you must meet specific authorization and permission requirements depending on the authentication method used [1][2][3]. Personal Access Tokens (PATs) For personal access tokens (classic), the token must have the 'repo' scope to successfully call this endpoint [1][2][3]. Fine-grained Access Tokens and GitHub Apps For fine-grained personal access tokens, as well as GitHub App user access tokens and installation access tokens, the token must be granted the 'Administration' repository permission with 'write' access [3]. General Authentication Notes This endpoint is available for GitHub Apps (user-to-server and installation-to-server) and fine-grained personal access tokens, provided they carry the required 'Administration' write permissions [3]. Ensure that the {environment_name} is properly URL-encoded if it contains special characters such as slashes (e.g., using %2F) [1][2][3]. If you encounter a 404 error despite having correct permissions, verify that the environment name is correctly encoded and that the environment exists within the specified repository [4].

Citations:

• 1: https://docs.github.com/enterprise-cloud@latest/rest/deployments/environments
• 2: https://docs.github.com/rest/deployments/environments
• 3: https://docs.github.com/enterprise-server@3.10/rest/deployments/environments
• 4: https://stackoverflow.com/questions/79138595/github-api-for-deleting-an-environment-does-not-work

---

The cleanup workflow cannot authorize the environment deletion API call.

administration is not a valid GITHUB_TOKEN workflow permission scope. GitHub Actions workflows support only: actions, checks, contents, deployments, issues, packages, pull-requests, repository-projects, security-events, and statuses. Line 16 cannot grant the access the delete call requires—the deleteAnEnvironment endpoint requires repository Administration write permission, which is not available to GITHUB_TOKEN. This workflow will fail at the deletion step.

Mint a GitHub App installation token via actions/create-github-app-token@v2 and pass it to the deletion step with github-token:, then remove line 16.

Suggested shape

 permissions:
   contents: read
   pull-requests: write
-  administration: write

+      - name: Mint repo-admin token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.REPO_ADMIN_APP_ID }}
+          private-key: ${{ secrets.REPO_ADMIN_APP_PRIVATE_KEY }}
+
       - name: Delete GitHub Preview environment
         uses: actions/github-script@v8
         with:
+          github-token: ${{ steps.app-token.outputs.token }}
           script: |
             const name = `pr-preview-${process.env.PR_NUMBER}`;
             try {
               await github.rest.repos.deleteAnEnvironment({

🧰 Tools

🪛 actionlint (1.7.12)

[error] 16-16: unknown permission scope "administration". all available permission scopes are "actions", "artifact-metadata", "attestations", "checks", "contents", "deployments", "discussions", "id-token", "issues", "models", "packages", "pages", "pull-requests", "repository-projects", "security-events", "statuses"

(permissions)

🪛 zizmor (1.25.2)

[warning] 16-16: overly broad permissions (excessive-permissions): administration: write is overly broad at the workflow level

(excessive-permissions)

🤖 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/cleanup-pr-preview.yml at line 16, Remove the invalid
permission line "administration: write" and instead mint a GitHub App
installation token using the actions/create-github-app-token@v2 action, then
pass that token into the environment deletion step via the github-token input;
update the job to call create-github-app-token (store its output as e.g.
github_app_token) and use that output in the deleteAnEnvironment call so the
repository Administration write scope is provided by the App token rather than
GITHUB_TOKEN.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Add explicit agent definitions and config fields to AGENTS.md.

This section defines reading order only; it still does not document concrete agent definitions and their configurations (roles, capabilities, constraints, required inputs/env, escalation/ownership), which is required for this file.

As per coding guidelines AGENTS.md: "AGENTS.md file should document agent definitions and their configurations".

🤖 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 `@AGENTS.md` around lines 3 - 8, Update AGENTS.md to add explicit agent
definitions and configuration fields: for each agent (give them clear
identifiers/names), document role, capabilities, constraints, required inputs
and environment variables, ownership/escalation path, expected outputs, and any
runtime/config flags; derive implemented/partial/deferred status from
docs/ops/project-status.md and cross-reference relevant domain language in
CONTEXT.md and specs in docs/specs/README.md; ensure each agent section uses
consistent field names (e.g., name, role, capabilities, constraints,
required_env, escalation_owner, status) so downstream code can parse these
entries.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Align read-order wording with AGENTS.md to avoid contradictory onboarding guidance.

Line 5 says this doc is read after CONTEXT.md/specs/ADRs, while AGENTS.md now instructs reading this doc first. Keep one canonical order across both docs.

🤖 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 `@docs/ops/project-status.md` at line 5, The docs conflict:
docs/ops/project-status.md currently states it is read after
CONTEXT.md/specs/ADRs while AGENTS.md says to read project-status.md first; pick
the canonical read order and make the wording consistent across both
files—either change the sentence in project-status.md that begins "First doc a
fresh agent reads after ..." to match AGENTS.md's “read first” phrasing, or
update AGENTS.md to instruct reading it after
CONTEXT.md/docs/specs/README.md/docs/adr/README.md; ensure the doc titles
(project-status.md, AGENTS.md, CONTEXT.md, docs/specs/README.md,
docs/adr/README.md) are referenced consistently and update the single line where
the order is described.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix markdownlint MD022 violations on backlog subsection headings.

Each ### backlog item heading needs a blank line after the heading. The current layout triggers the reported MD022 warnings.

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 166-166: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 171-171: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 176-176: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 181-181: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 186-186: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 191-191: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 196-196: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 201-201: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 206-206: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 211-211: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 216-216: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 221-221: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 226-226: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 231-231: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 236-236: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 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 `@docs/ops/project-status.md` around lines 166 - 236, MD022 errors come from
missing blank lines immediately after level-3 backlog headings; edit the
Markdown document and insert a single blank line after each "###" backlog
heading (e.g., "### 1. Wire `runCommand` and `createOperationEvent` into
mutation routes", "### 2. Enforce native rate-limit bindings", etc.) so every
level-3 heading is followed by exactly one empty line before the next paragraph
or list item, then run markdownlint to verify the MD022 warnings are resolved.

[github-actions]

agent-paste PR preview is ready.

API: https://agent-paste-api-pr-2.isaac-a46.workers.dev
Upload: https://agent-paste-upload-pr-2.isaac-a46.workers.dev
Content: https://agent-paste-content-pr-2.isaac-a46.workers.dev
Apex: https://agent-paste-apex-pr-2.isaac-a46.workers.dev
Neon branch: https://console.neon.tech/app/projects/still-forest-91029005/branches/br-withered-glitter-aphpkof8

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In @.github/workflows/pr-preview.yml:
- Around line 110-119: The timeout message "did not become reachable within 60s"
is incorrect for the retry loop using i, curl --max-time 5 and sleep 2 across 30
attempts (worst-case ~210s); update the error reporting to reflect the actual
wait window by either changing the static message to the correct value (e.g.,
"~210s") or compute and report the real elapsed time using shell SECONDS (set
SECONDS=0 before the loop and include $SECONDS in the ::error:: message) so the
failure log accurately shows how long the script waited.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ebfcf8f3-ccfb-4fd5-978a-3ad51143ef82

📥 Commits

Reviewing files that changed from the base of the PR and between b41136f and f43d07a.

📒 Files selected for processing (1)

• .github/workflows/pr-preview.yml

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Timeout message is inconsistent with the implemented retry window.

The loop can run for ~210 seconds, but Line 118 reports a 60-second timeout. This makes failures harder to interpret during CI incidents.

Suggested fix

           wait_for() {
             local url="$1"
+            local attempts=30
+            local curl_timeout=5
+            local sleep_seconds=2
+            local max_wait=$((attempts * (curl_timeout + sleep_seconds)))
             local i=0
-            while [ $i -lt 30 ]; do
+            while [ $i -lt "$attempts" ]; do
               i=$((i+1))
-              if curl -sS -o /dev/null --max-time 5 "$url"; then
+              if curl -sS -o /dev/null --max-time "$curl_timeout" "$url"; then
                 echo "$url reachable after $i attempt(s)"
                 return 0
               fi
-              sleep 2
+              sleep "$sleep_seconds"
             done
-            echo "::error::$url did not become reachable within 60s"
+            echo "::error::$url did not become reachable within ${max_wait}s"
             return 1
           }

🤖 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.yml around lines 110 - 119, The timeout message
"did not become reachable within 60s" is incorrect for the retry loop using i,
curl --max-time 5 and sleep 2 across 30 attempts (worst-case ~210s); update the
error reporting to reflect the actual wait window by either changing the static
message to the correct value (e.g., "~210s") or compute and report the real
elapsed time using shell SECONDS (set SECONDS=0 before the loop and include
$SECONDS in the ::error:: message) so the failure log accurately shows how long
the script waited.