CI/CD

wrangler-deploy uses wrangler under the hood. CI runs the same wrangler.jsonc configs your local dev uses, unchanged. This page covers setting up pipelines that create PR preview environments automatically and clean them up on merge.

Authentication

Set these environment variables in your CI:

CLOUDFLARE_API_TOKEN=xxx     # required
CLOUDFLARE_ACCOUNT_ID=xxx    # required unless the account id is set another way (see below)

You must give wrangler-deploy a 32-character hexadecimal Cloudflare account id when using an API token, either:

• CLOUDFLARE_ACCOUNT_ID in the job environment (wins over .wdrc when both are set), or
• accountId in .wdrc / .wdrc.json at the repo root (for example commit the file or run wd context set --account-id … once and commit the result).

If wrangler whoami succeeds in CI with the same token and scopes, resolution can work without CLOUDFLARE_ACCOUNT_ID—but pinning the id explicitly avoids flaky pipelines and documents intent.

When CLOUDFLARE_API_TOKEN is set, wrangler-deploy does not read ~/.wrangler/config/default.toml for the account. That OAuth file is often a personal login while the token targets another account; mixing them leads to Cloudflare API error 10000.

More detail: How it works — Authentication.

For PR comments and check runs, also set:

GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}

Pipeline

A minimal CI pipeline is two commands:

$ wd apply --stage pr-42
  + payments-db-pr-42 (d1) created
  + token-kv-pr-42 (kv) created
  + payment-outbox-pr-42 (queue) created
  ✓ 3 resources applied

$ wd deploy --stage pr-42 --verify
  ✓ payment-api-pr-42 deployed
  ✓ payment-batch-workflow-pr-42 deployed
  Verification: 8 passed, 0 failed

--verify runs post-deploy coherence checks and fails the pipeline if anything is wrong.

Generate a workflow

Run this once to set up CI/CD:

$ wd ci init --branch main
  ✓ Generated .github/workflows/wrangler-deploy.yml

The generated workflow has three jobs:

• preview (on PR open/sync) — wd apply + wd deploy --verify + wd ci comment + wd ci check
• cleanup (on PR close) — wd destroy
• deploy (on push to main) — wd apply + wd deploy --verify for production

CI subcommands

wd ci comment --stage <name>

Posts or updates a PR comment with worker URLs, a Mermaid topology diagram, resource tables, and secret status. Uses a <!-- wrangler-deploy --> HTML marker to update the same comment on subsequent pushes instead of creating new ones.

wd ci check --stage <name>

Posts a GitHub check run. If no state exists for the stage, the check reports failure and the command exits 1:

# Stage deployed successfully
$ wd ci check --stage pr-42
  ✓ Check run posted for pr-42

# Stage was never applied
$ wd ci check --stage pr-99
  ✗ No state found for stage "pr-99"
  (exit code 1)

Without this, CI would pass silently on a stage that was never deployed.

Permissions

The generated workflow declares these permissions:

permissions:
  contents: read
  issues: write
  checks: write

If you write your own workflow, include these — without them, ci comment and ci check fail with 403 errors in repos that restrict the default GITHUB_TOKEN scope.