Cloudflare deployment

Status: Current
Reviewed: July 24, 2026
Cadence: Review after a Cloudflare build change

Workers Builds owns the normal production build and deploy. GitHub Actions validates the PR. GitHub Actions must not also run the normal production deploy.

When you ship a Worker change, merge is not deploy. Deploy is the Workers Builds run on the merged default-branch commit.

Branch contract

The default branch is the production source.
Pull requests may create preview builds.
A failed Cloudflare build cannot change production.
Cloudflare records the deployed commit and build result.
GitHub owns merge checks. Cloudflare owns deploy checks.

Build commands

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

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. Generate Wrangler binding types for TypeScript Workers.

Store secret values in the Cloudflare environment. Keep only secret names and value-free wiring in the repository.

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.

Run a repository cf:check in GitHub CI before merge. That command must build the deployable output and run wrangler deploy --dry-run.

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