Prepare Cloudflare Production Deployment

Prepare Cloudflare Production

Overview

Use this skill as the source of truth for production deployment. Cloudflare MCP must be used for Cloudflare account/resource discovery, verification, and supported mutations before using Wrangler, raw API calls, dashboard instructions, or assumptions. Use gh for GitHub repository secrets/variables; edit repo files directly for project branding, wrangler.jsonc, and workflow changes.

Never print secret values. Ask for missing secret values instead of inventing placeholders, and confirm before creating paid, destructive, or externally visible resources.

Preflight

1. Read wrangler.jsonc, package.json, .github/workflows/deploy.yml, src/constants.ts, src/utils/root-metadata.ts, src/components/footer.tsx, AGENTS.md, and cms.config.ts when relevant.
2. Check GitHub auth, then complete the MCP availability gate before any Cloudflare mutation:

gh auth status
gh repo view --json nameWithOwner,url

Report the Cloudflare account id/name/email from MCP and the GitHub account/repository from gh, then ask whether both are correct. Stop if the user says either account is wrong.

3. Confirm or remind the user about the required production customization checklist:

   • src/constants.ts has project details.
   • Read SITE_URL from src/constants.ts, derive the hostname, and check the domains/zones available in the authenticated Cloudflare account. Tell the user which matching or closest Cloudflare zone/domain was found and ask them to confirm it before proceeding. If the SITE_URL domain is not available in Cloudflare, stop and ask the user which Cloudflare zone/domain to use or whether they need to add the domain to Cloudflare first.
   • When the app will use Cloudflare Images, verify Images against that same production zone/hostname, not only against the account. Confirm the SITE_URL hostname belongs to a Cloudflare zone in the authenticated account and is proxied or attached as the Worker custom domain/route that production will use. Then verify the account-level Images API works for that account with /accounts/{account_id}/images/v1/variants or /accounts/{account_id}/images/v1/stats. If custom-domain image delivery is expected, explicitly confirm the production zone can serve Images URLs at https://<SITE_URL_HOSTNAME>/cdn-cgi/imagedelivery/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>; Cloudflare supports this only for customer domains under the same account as the Images account. If the domain is in a different account, not proxied through Cloudflare, or not the domain being deployed to, stop and ask which zone/domain should be used before proceeding.
   • Read package.json, tell the user the current name value, and ask them to confirm it is the intended production project name. This value controls generated deploy-size metrics and package metadata, so do not proceed if it still identifies the reused template. If the name is still cloudflare-workers-nextjs-saas-template, stop and ask the user for the real project name and production domain before editing Cloudflare resources, queue names, bindings, or deployment metadata.
   • Check queue names in wrangler.jsonc, especially queues.producers[].queue and queues.consumers[].queue. Queue names must be renamed to match the new production project name; do not leave template queue names such as cloudflare-workers-nextjs-saas-template-scheduler in a production project unless the user explicitly confirms that is the real project name.
   • Email Sending must follow the Email Sending procedure below: use the production SITE_URL zone, expect notifications.<SITE_URL_HOSTNAME>, and get user confirmation before Cloudflare or wrangler.jsonc changes.
   • AGENTS.md has the project specification for AI coding agents.
   • src/components/footer.tsx has project links and details.
   • src/app/globals.css color palette has been reviewed.
   • src/utils/root-metadata.ts metadata has project details; both root layouts read it.
   • The meta titles and descriptions in every locale catalog under src/i18n/messages/*.json (for example Client.Landing.meta, plus the auth, legal, and blog meta blocks) still default to template copy. Explicitly ask the user for the production titles and descriptions, and help them update these values in all locale catalogs, not only en.json.
   • cms.config.ts has been reviewed and updated if needed.

4. Collect required inputs:

   • Project name and production domain.
   • Confirmed Cloudflare account id and production zone id.
   • Sending email address, reply-to address, and sender display name.
   • GitHub repository owner/name if it differs from the current checkout.
   • Required values from Required configuration buckets.

5. Follow Deployment Verification after deployment-related file or runtime configuration changes.

Automation Map

Cloudflare MCP Patterns

Cloudflare MCP is not optional for Cloudflare operations. Always try it first for account/resource reads and supported writes. Wrangler, raw curl, and dashboard instructions are fallback paths only.

MCP availability gate

At the start of deployment prep, before any Cloudflare mutation:

1. Confirm Cloudflare MCP tools are installed/available in the current session.
2. Confirm Cloudflare MCP can identify the authenticated Cloudflare account.
3. Report the Cloudflare account id/name/email from MCP to the user.
4. If MCP is missing, not logged in, or cannot identify the account, warn the user and pause Cloudflare resource changes. The warning must include:
   • Which MCP capability is missing or failing.
   • That Wrangler/raw API/dashboard fallback can diverge from the required MCP-audited workflow.
   • The smallest next action: install/enable Cloudflare MCP, log in to Cloudflare MCP, or explicitly approve a fallback.

Only continue with Wrangler/raw API/dashboard fallback after the user explicitly approves that fallback or MCP cannot support the needed product operation.

Use idempotent create-or-reuse behavior:

1. List existing resources by name.
2. Reuse exact matches.
3. Create only when missing and the user has approved the final names.
4. Store returned ids in wrangler.jsonc.

Common endpoint families to search and use:

Zones/domains: /zones
D1: /accounts/{account_id}/d1/database
KV: /accounts/{account_id}/storage/kv/namespaces
R2: /accounts/{account_id}/r2/buckets
Queues: /accounts/{account_id}/queues
Turnstile: /accounts/{account_id}/challenges/widgets
Worker secrets: /accounts/{account_id}/workers/scripts/{script_name}/secrets
API tokens: /accounts/{account_id}/tokens
Email Sending: /zones/{zone_id}/email/sending/subdomains
Images: /accounts/{account_id}/images/v1
Images variants and stats: /accounts/{account_id}/images/v1/variants, /accounts/{account_id}/images/v1/stats
Images custom-domain delivery check: resolve SITE_URL hostname to a same-account zone, then verify or document delivery through https://<hostname>/cdn-cgi/imagedelivery/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>
Cache purge: /zones/{zone_id}/purge_cache

When a Cloudflare step is blocked by billing, product enablement, token permissions, DNS propagation, or account approval, report the exact blocker and give the smallest dashboard action needed.

Secret Handling

Do not print secret values in chat, logs, diffs, or command output. Secret creation/provisioning is a user-only manual step unless the secret is returned by an explicitly approved product API flow, such as creating a new Turnstile widget. Prefer secure prompts and never invent placeholders.

Required configuration buckets

Before pushing or deploying through GitHub Actions, explicitly tell the user which values belong in each bucket and whether they already exist:

1. GitHub Actions secrets are available only to the GitHub workflow. For the current deploy workflow, the required secret is CLOUDFLARE_API_TOKEN; the user must create/provide it manually and paste it into the secure gh prompt.
2. GitHub Actions variables are non-secret values available to the GitHub workflow. Set CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_ZONE_ID, enabled NEXT_PUBLIC_* values, and remember the deploy workflow auto-forwards repository NEXT_PUBLIC_* variables into the build.
3. Worker runtime secrets are available to the deployed Worker, not to GitHub Actions. Ask the user to supply enabled-feature secrets such as CLOUDFLARE_API_TOKEN, TURNSTILE_SECRET_KEY, STRIPE_SECRET_KEY, and GOOGLE_CLIENT_SECRET through secure prompts or supported MCP secret writes.
4. Worker runtime variables are non-secret values available to the deployed Worker. Put CLOUDFLARE_ACCOUNT_ID in wrangler.jsonc under vars (see the CLOUDFLARE_ACCOUNT_ID section). Prefer vars for other stable values such as GOOGLE_CLIENT_ID; otherwise use Cloudflare MCP/dashboard/API.

After setting repository configuration, verify without exposing values:

gh secret list --repo OWNER/REPO
gh variable list --repo OWNER/REPO

After setting Worker secrets, verify behavior by exercising the relevant feature or checking the Worker dashboard secret names. Do not attempt to read secret values back.

CLOUDFLARE_API_TOKEN:

1. Apologize to the user that, unfortunately, Cloudflare API token creation is not supported by the current Cloudflare MCP workflow. Always ask the user to create/provide this token manually. Do not try to create, roll, retrieve, guess, or reuse Cloudflare API tokens through Cloudflare MCP/API or repository history.
2. Send the user to https://dash.cloudflare.com/profile/api-tokens.
3. Tell them to click Use template next to Edit Cloudflare Workers.
4. Tell them to add these permissions in addition to the template defaults:
   • Account:AI Gateway:Edit
   • Account:Workers AI:Edit
   • Account:Workers AI:Read
   • Account:Queues:Edit
   • Account:Vectorize:Edit
   • Account:D1:Edit
   • Account:Cloudflare Images:Edit
   • Account:Workers KV Storage:Edit
   • Account:Email Sending:Edit
   • Account:Turnstile Sites:Edit or Account:Turnstile Sites:Read plus dashboard access if only reading existing widgets
   • Zone:Cache Purge:Purge
5. Tell them to scope the token to the intended Cloudflare account and, when zone permissions are needed, the intended production zone.
6. Tell the user this token is used in two contexts:
   • GitHub Actions uses CLOUDFLARE_API_TOKEN for deploy, D1 migrations, and cache purge.
   • The deployed Worker uses CLOUDFLARE_API_TOKEN for the admin scheduled jobs page to preview Cloudflare Queue payloads, and for the admin "Purge Cloudflare CDN Cache" action. Native Queue binding metrics do not need this token, but payload preview and the purge do. The purge needs Zone:Cache Purge:Purge, resolves its zone from the Workers domain of the site host, and is hidden in the panel when the token is absent.
7. After they provide the token, add it to GitHub Actions without printing it:

gh secret set CLOUDFLARE_API_TOKEN --repo OWNER/REPO

Paste the token only into the secure gh prompt. Verify the secret exists with:

gh secret list --repo OWNER/REPO

8. Also set the token as a Worker secret for runtime admin Queue preview:

pnpm wrangler secret put CLOUDFLARE_API_TOKEN

CLOUDFLARE_ACCOUNT_ID:

1. Set CLOUDFLARE_ACCOUNT_ID as a GitHub Actions variable for deploy/migrations:

gh variable set CLOUDFLARE_ACCOUNT_ID --body "$ACCOUNT_ID" --repo OWNER/REPO

2. Set CLOUDFLARE_ACCOUNT_ID in wrangler.jsonc under vars, with the same value as the top-level account_id. The deployed Worker needs it for these features:

   • The zone lookup in getWorkerZoneId (src/lib/cloudflare-api.ts). Without the var, the lookup fails with a getWorkerZoneId: zone lookup failed warning. The CMS publish then purges stored HTML only in one data center, and the admin "Purge Cloudflare CDN Cache" action is hidden. Setting CLOUDFLARE_ZONE_ID skips this lookup.
   • The admin scheduled jobs Queue payload preview.

   Do not set it as a Worker secret. The account id is not a secret, and a secret with the same name as a vars entry makes wrangler deploy fail. If a Worker secret CLOUDFLARE_ACCOUNT_ID already exists, delete it before the deploy that adds the var: