Cloudflare deployment

Status

Current

Reviewed

October 14, 2026

Cadence

Review after a Cloudflare build change

Workers Builds owns the production and staging Worker build and deploy. GitHub Actions validates the pull request.

The canonical toolchain for Vite-ready Workers with a Worker entry is cf CLI + Vite + @cloudflare/vite-plugin + typed cloudflare.config.ts, and only when the project build produces BOS. See cf CLI and cloudflare.config.ts. Wrangler is transitional for assets-only Astro and other whitelist cases. Do not delete wrangler.jsonc yet.

A repository that still runs wrangler deploy, cf deploy, or remote D1 migrate from GitHub Actions is out of conformance. That path is a violation to close. It is not an approved exception.

When you ship a Worker change, merge is not deploy. Deploy is the Workers Builds run on the merged production-branch commit. The account listener for a failed or missing build is Workers Builds notify.

Branch contract

• The protected production branch is the production source.
• Disable non-production branch builds unless a separate staging Worker exists.
• Disable Deploy Hooks.
• A failed Cloudflare build cannot change production.
• Cloudflare records the deployed commit and build result.
• GitHub owns merge checks. Cloudflare owns deploy checks.
• GitHub Pages and GitHub Packages publish are not Worker deploys.

Build commands

Static reference site

Use pnpm --dir site build. Set the output directory to site/dist. Point Workers Static Assets at that directory.

This architecture site still deploys with Wrangler through Workers Builds. That is transitional. It is assets-only Astro with no Worker entry — the same shape as the first pilots. Do not migrate mnppi-architecture in a docs-only change. Do not point Builds at wrangler --experimental-new-config.

Worker application

Run the production app build. Deploy with cf deploy through Workers Builds only when BOS (.cloudflare/output/v0/config.json) exists after that build. Keep D1, R2, KV, and other bindings in cloudflare.config.ts for Worker-entry apps.

Use Wrangler through Workers Builds when the transitional whitelist or pilot-proven fences apply. Label that repo transitional. Keep wrangler.jsonc.

Database application

Validate migrations locally in GitHub before merge. Apply production migrations in the Workers Builds deploy command, immediately before cf deploy (or transitional wrangler deploy). Stop the deploy if a required migration fails.

Static delivery

Use Static Assets for files that do not need server code. Do not invoke a Worker for every asset request. If /index.html or /assets/* hit the Worker, you pay CPU for free.

If you set assets.run_worker_first, list only dynamic route patterns. Confirm that documents, scripts, styles, images, and fonts bypass Worker code.

Configuration

Use bindings for D1, R2, KV, Queues, Durable Objects, and other services. For Vite-ready Worker-entry apps, runtime config is cloudflare.config.ts (defineConfig / bindings / triggers from cf/config). Branch those environments with Vite/CLI mode, not Wrangler nested env.* blocks. Generate binding types with cf workers types.

Assets-only Astro and any repo without BOS keep labeled transitional wrangler.jsonc as the deploy config. Do not treat cloudflare.config.ts as the fleet-wide sole source yet.

Store secret values in the Cloudflare environment. Keep only secret names and value-free wiring in the repository. Wrangler deploys never delete secrets. Declare names in secrets.required. Put every non-secret plain var in committed config vars or env blocks. Dashboard-only plain vars are a migration smell, not the end state. See Worker secrets and vars.

keep_vars is a Wrangler field. It does not apply to secrets. cf has no keep_vars. cf migrate does not convert it. Use keep_vars only while you copy dashboard-only plain vars into config. Then remove it. Do not invent a cf keep-vars flag. Do not commit example values for production plain vars. Tests and local .dev.vars can supply examples.

cf migrate must not drop FedRAMP D1 UUID pins. See the cf CLI standard.

Build parity

The lockfile must support a frozen, tokenless install for public packages. Use pnpm install --frozen-lockfile without --trust-lockfile. Do not set trustLockfile: true in pnpm-workspace.yaml. Those options disable pnpm lockfile supply-chain checks. When the install graph contains @mnppi/*, Workers Builds needs a per-trigger NODE_AUTH_TOKEN Build secret plus .npmrc.builds. Manage Actions access does not authenticate that install. See docs/private-package-distribution.md.

Every image that installs or runs cf needs Node.js ≥ 22. The CLI refuses to run on Node 20.

Run a repository cf:check in GitHub CI before merge. That command must build the deployable output and dry-run the same deploy tool Workers Builds will use: cf deploy --dry-run when BOS exists, otherwise wrangler deploy --dry-run. Keep the script name cf:check.

The Cloudflare build must not depend on a developer workstation. Keep Workers Builds limited to the real post-merge build and deploy.

Release evidence

For normal projects, the deployed commit, Cloudflare build result, and service health are enough. Add signed artifacts only when risk or a customer requirement demands them.