docs(e2e): document TEST_CLOUDFLARE_* for mint-test Worker

[ifireball]

Summary

• Document TEST_CLOUDFLARE_ACCOUNT_ID / TEST_CLOUDFLARE_API_TOKEN in the e2e guide (mapped to Wrangler CLOUDFLARE_* env names in the behaviour job).
• Clarify isolation from site-deploy CLOUDFLARE_*, intended Worker mint-test, and preview-URL usage via versions upload --preview-alias.

Related Issue

Closes #5222

Ops (already done outside this PR)

• Set real TEST_CLOUDFLARE_ACCOUNT_ID and TEST_CLOUDFLARE_API_TOKEN on fullsend-ai/fullsend (token fullsend-ai/fullsend-mint-test).
• Smoke-verified with wrangler whoami and wrangler deployments list --name=mint-test.

Changes

• Update docs/guides/dev/e2e-testing.md secrets inventory and operator notes.

Testing

• make lint (staged docs)
• Wrangler auth smoke test against mint-test
• N/A for code tests (docs only)

Checklist

• PR title follows Conventional Commits
• Commits signed off (DCO)
• I wrote this contribution myself and can explain all changes in it

Made with Cursor

[qodo-code-review]

PR Summary by Qodo

docs(e2e): document TEST_CLOUDFLARE_* secrets for mint-test Worker

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Document TEST_CLOUDFLARE_* secrets used by e2e behaviour tests via Wrangler.
• Clarify isolation from site-deploy CLOUDFLARE_* and target Worker mint-test.
• Add operator guidance for preview-alias usage and token rotation.

Diagram

graph TD
  A["GitHub Secrets: TEST_CLOUDFLARE_*"] --> B["CI: behaviour job"] --> C["Wrangler env: CLOUDFLARE_*"] --> D["Wrangler CLI"] --> E["Cloudflare API"] --> F["Worker: mint-test"] --> G["Preview URL via preview-alias"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Reuse site-deploy CLOUDFLARE_* secrets for tests

• ➕ Fewer secrets to manage
• ➕ No env-var mapping needed in the behaviour job
• ➖ Higher blast radius if test jobs leak or over-permission tokens
• ➖ Entangles test and production deployments, increasing operational risk
• ➖ Harder to rotate independently without impacting site deployments

2. Use GitHub Environments for test-only Cloudflare credentials

• ➕ Adds approvals/auditing for sensitive deploy credentials
• ➕ Clear separation between test and production secret scopes
• ➖ More CI wiring/maintenance (environment selection, permissions, approvals)
• ➖ Potentially slows e2e runs if approvals are required

Recommendation: Keep the PR’s approach: dedicated TEST_CLOUDFLARE_* secrets mapped into Wrangler’s CLOUDFLARE_* env vars, with explicit guidance to avoid reusing site-deploy credentials. This is the safest operational posture for CI-driven Worker uploads, and the added doc sections (preview-alias and rotation guidance) directly reduce on-call confusion and credential mistakes.

Files changed (1) +14 / -0

Documentation (1) +14 / -0

e2e-testing.mdAdd Cloudflare mint-test secrets, preview-alias guidance, and rotation notes +14/-0

Add Cloudflare mint-test secrets, preview-alias guidance, and rotation notes

• Extends the e2e secrets inventory with TEST_CLOUDFLARE_ACCOUNT_ID and TEST_CLOUDFLARE_API_TOKEN, documenting how the behaviour job maps them to Wrangler’s CLOUDFLARE_* env vars. Adds operator notes on isolating these from site-deploy credentials, using wrangler versions upload with preview-alias against Worker mint-test, and rotating the test token safely.

docs/guides/dev/e2e-testing.md

[github-actions]

Site preview

Preview: https://2ce0da17-site.fullsend-ai.workers.dev

Commit: 3372719bdaf905b2beade60ceeb5a912358d64ca

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (3)

Context used

✅ Tickets: 🎫 e2e: provision test-scoped Cloudflare token and set real TEST_CLOUDFLARE_* secrets

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Token rotation not numbered 📜 Skill insight ✧ Quality

Description

The newly added Cloudflare token rotation procedure is written as prose instead of numbered steps.
This makes the procedure harder to follow and violates the requirement that procedural content use
ordered lists.

Code

docs/guides/dev/e2e-testing.md[R234-238]

+**Cloudflare test token rotation:** Create a new Account API token with Workers
+Edit (or the Edit Cloudflare Workers template), store it as
+`TEST_CLOUDFLARE_API_TOKEN`, and keep `TEST_CLOUDFLARE_ACCOUNT_ID` aligned with
+the account that hosts Worker `mint-test`. Do not put the new value into
+site-deploy `CLOUDFLARE_API_TOKEN`.

Relevance

⭐⭐⭐ High

Team often enforces numbered steps for procedures (accepted in PR #2277 and #2663).

PR-#2277
PR-#2663

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The rule requires procedural instructions to be expressed as numbered steps. The added "Cloudflare
test token rotation" instructions are procedural (create token, store secret, align account ID,
avoid site-deploy secret) but are presented as a prose paragraph.

docs/guides/dev/e2e-testing.md[234-238]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Cloudflare token rotation instructions are procedural but not formatted as a numbered list.

## Issue Context
Documentation procedures must use numbered (ordered) steps rather than prose paragraphs.

## Fix Focus Areas
- docs/guides/dev/e2e-testing.md[234-238]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Wrangler jargon undefined 📜 Skill insight ✧ Quality

Description

The added section introduces Cloudflare/Wrangler-specific jargon without an inline definition or a
glossary link on first use. This reduces readability for readers unfamiliar with the Cloudflare
toolchain.

Code

docs/guides/dev/e2e-testing.md[R70-72]

+The behaviour job wires `TEST_CLOUDFLARE_*` into Wrangler’s standard `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` env names so CF mint BT (#5109) can upload versions of Worker **`mint-test`**. These secrets must **not** reuse the production site-deploy `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` used by `site-deploy.yml` (Worker `site`).
+
+Prefer **`wrangler versions upload --name=mint-test --preview-alias=…`** so runs use preview URLs (`<alias>-mint-test.<subdomain>.workers.dev`) rather than inventing new Worker names or relying on the production `mint-test.…workers.dev` route (which may stay disabled). Cloudflare Account API tokens cannot currently attach Workers Scripts permissions under a Specified-Workers-only policy; operators use a dedicated Workers Edit token (for example `fullsend-ai/fullsend-mint-test`) that is separate from site-deploy credentials and intended only for this test path.

Relevance

⭐⭐ Medium

Mixed history: defining terms sometimes accepted (PR #665) but “define on first use” also rejected
(PR #2756).

PR-#665
PR-#2756

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The rule requires jargon to be defined or linked to a glossary when first introduced. The added
lines reference Wrangler and related Cloudflare concepts without providing a definition or
glossary link in the same first-use context.

docs/guides/dev/e2e-testing.md[70-72]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
New Cloudflare-specific terms (e.g., `Wrangler`, `preview-alias`, "Specified-Workers-only policy") are introduced without being defined or linked to a glossary on first use.

## Issue Context
Guide jargon must be defined on first use via a glossary link or an inline definition.

## Fix Focus Areas
- docs/guides/dev/e2e-testing.md[70-72]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Wrong directory for e2e-testing.md 📜 Skill insight ⌂ Architecture

Description

This guide is under docs/guides/dev/, but guides must live under either docs/guides/admin/ or
docs/guides/user/ and target a single audience. The new Cloudflare sections add operator-focused
credential management into a developer guide, reinforcing mixed-audience content.

Code

docs/guides/dev/e2e-testing.md[R68-72]

+### Cloudflare Worker mint BT credentials
+
+The behaviour job wires `TEST_CLOUDFLARE_*` into Wrangler’s standard `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` env names so CF mint BT (#5109) can upload versions of Worker **`mint-test`**. These secrets must **not** reuse the production site-deploy `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` used by `site-deploy.yml` (Worker `site`).
+
+Prefer **`wrangler versions upload --name=mint-test --preview-alias=…`** so runs use preview URLs (`<alias>-mint-test.<subdomain>.workers.dev`) rather than inventing new Worker names or relying on the production `mint-test.…workers.dev` route (which may stay disabled). Cloudflare Account API tokens cannot currently attach Workers Scripts permissions under a Specified-Workers-only policy; operators use a dedicated Workers Edit token (for example `fullsend-ai/fullsend-mint-test`) that is separate from site-deploy credentials and intended only for this test path.

Relevance

⭐ Low

Similar “move docs/guides/dev → user/admin” suggestion was rejected in PR #4901.

PR-#4901

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The checklist requires guides under docs/guides/ to be placed in admin/ or user/ and to target
only one audience. The added Cloudflare credential/operator guidance appears in
docs/guides/dev/e2e-testing.md, which is neither admin/ nor user/ and adds operator-focused
instructions inside the guide.

docs/guides/dev/e2e-testing.md[68-72]
docs/guides/dev/e2e-testing.md[234-238]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/guides/dev/e2e-testing.md` violates the guide placement/audience rule: it is not located under `docs/guides/admin/` or `docs/guides/user/`, and the newly added Cloudflare credential/operator guidance contributes to mixed-audience content.

## Issue Context
The compliance requirement for guides is to (1) place them in the correct directory (`admin/` or `user/`) and (2) keep each guide targeted to a single audience.

## Fix Focus Areas
- docs/guides/dev/e2e-testing.md[68-72]
- docs/guides/dev/e2e-testing.md[234-238]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:08 AM UTC · Completed 8:24 AM UTC
Commit: 3372719 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5310 — docs(e2e): document TEST_CLOUDFLARE_* for mint-test Worker

What happened

PR #5310 was a small docs-only change (+14/−0 lines, single file docs/guides/dev/e2e-testing.md) documenting Cloudflare test credentials for the mint-test Worker. It originated from issue #5222, which the triage agent correctly classified as a manual infrastructure task requiring Cloudflare admin and GitHub admin access — it did not route to the code agent (correct decision).

The PR was authored by ifireball with Cursor co-authorship, opened Jul 19 10:31 UTC, approved by rh-hemartin Jul 20 07:06 UTC, and merged Jul 20 08:05 UTC.

Review agent failure

The fullsend review agent was correctly dispatched (run 29683511838) when the PR was opened, but failed after ~48 seconds with: minted agent token contains unexpected characters for role review. This is the known JWT token format validation bug tracked in #4983 (priority/critical) — GitHub is rolling out new JWT-format installation tokens containing dots, which the current regex (^[a-zA-Z0-9_-]+$) rejects. Fix PR #5342 is open but not yet merged.

As a result, the PR was merged with zero fullsend review agent coverage. The only automated review came from qodo-code-review, which flagged 3 non-blocking style findings (token rotation procedure formatting, Wrangler jargon definitions, guide file location). The human reviewer approved without addressing these — a reasonable judgment for a small docs-only change.

Evidence for existing issues

This PR is a concrete example of multiple tracked gaps compounding:

• #4983 (priority/critical): The root cause. This failure was intermittent at the time but will become 100% once GitHub completes the JWT rollout. PR fix(#4983): accept dots in minted GitHub token validation #5342 adds a single . to the regex character class — merging it is time-sensitive.
• #2711: Had auto re-dispatch existed, the review agent would have retried and likely succeeded (the failure is intermittent, and no subsequent PR event triggered a re-dispatch since pull_request_review only dispatches the fix agent on changes_requested).
• #4325: Neither the PR author nor the human reviewer received any notification that the review agent failed. A visible failure comment would have prompted a /fs-review re-trigger.
• #4768: A post-merge informational review would have provided a safety net, catching any issues the human reviewer missed.

Assessment

The workflow went well overall. The triage agent made the right routing call, the human author and reviewer handled the docs-only change appropriately, and the review agent was correctly dispatched — it just couldn't mint a token. All identified gaps are already tracked by existing open issues with clear fix paths. No new proposals are warranted.