Deploy & Verify

Deploy Cloudflare Workers to an environment and verify the changes work by inferring what to test from recent git changes.

Workflow

1. Pre-deploy checks
2. Deploy to target environment
3. Infer verification plan from git diff
4. Run verification
5. Report results (pass/flag issues)

Step 1: Pre-Deploy Checks

Before deploying, verify:

1. Types pass — tsc --noEmit or project equivalent
2. Tests pass — npm test / bun test / project equivalent
3. No uncommitted changes — git status should be clean (warn if dirty)
4. Detect environment config — read wrangler.toml / wrangler.jsonc for available environments

# List available environments from wrangler config
grep -E '^\[env\.' wrangler.toml | sed 's/\[env\.\(.*\)\]/\1/'

Step 2: Deploy

# To a named environment (staging, preview, etc.)
wrangler deploy --env <environment>

# To production (default if no --env)
wrangler deploy

If the project has multiple Workers (monorepo), detect which one changed:

• Check git diff --name-only for paths matching Worker directories
• Only deploy the Worker(s) that changed

Step 3: Infer Verification Plan

This is the key step. Look at what changed and determine what to verify:

# What changed since last deploy?
git diff HEAD~1 --name-only
git diff HEAD~1 --stat
git log HEAD~1..HEAD --oneline

Inference rules:

Change type	What to verify
API route handler changed	Hit that endpoint, check response shape and status
Middleware changed	Test requests that flow through it
Auth logic changed	Test both authenticated and unauthenticated requests
KV/D1/R2 bindings changed	Test read/write operations on those bindings
Environment variables referenced	Verify secrets are set: wrangler secret list --env <env>
CORS or headers changed	Check response headers
Error handling changed	Test error paths
New route added	Hit the new route, verify 200 + correct response
Route removed	Verify it returns 404
Static assets changed	Fetch them and verify content

Step 4: Run Verification

Use curl or fetch to test the deployed URL:

# Basic health check
curl -s -o /dev/null -w "%{http_code}" https://<worker-url>/

# Check specific endpoint with response body
curl -s https://<worker-url>/api/endpoint | jq .

# Check response headers
curl -sI https://<worker-url>/api/endpoint

# POST with body
curl -s -X POST https://<worker-url>/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Also check wrangler logs for errors after hitting endpoints:

# Tail logs (run in background, hit endpoints, then check)
wrangler tail --env <environment> --format json

Step 5: Report

If all checks pass:

Deploy verified:
- Environment: staging
- URL: https://my-worker-staging.example.workers.dev
- Checks passed:
  - GET /api/stories → 200, response shape correct
  - POST /api/generate → 200, returns stream
  - KV read/write → working

If issues found (flag, don't rollback):

Deploy issues found:
- Environment: staging
- URL: https://my-worker-staging.example.workers.dev
- PASS: GET /api/stories → 200
- FAIL: POST /api/generate → 500
  - Error in logs: "Missing AI binding"
  - Likely cause: AI binding not configured in staging env
- Action needed: Check wrangler.toml [env.staging] AI bindings

Do NOT automatically rollback. Flag the issues and let the user decide.

Multi-Environment Patterns

Common setup:

# wrangler.toml
name = "my-worker"

[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"

[env.production]
name = "my-worker"
route = "example.com/*"

Default flow: Deploy to staging → verify → user promotes to production. Direct to prod: Only when user explicitly asks. Still run verification after.

Secrets

If verification fails with auth/config errors, check that secrets match between environments:

wrangler secret list --env staging
wrangler secret list --env production

Secrets don't copy between environments. A common gotcha after adding a new env.

Troubleshooting

Problem	Fix
500 after deploy	wrangler tail --env <env> to see error logs
Binding not found	Check wrangler.toml — bindings must be declared per environment
Secret missing	wrangler secret put <NAME> --env <env>
Old code still serving	Worker may be cached — wait 30s or check wrangler deployments list
Route not matching	Verify route patterns in wrangler.toml match the URL you're hitting
CORS errors	Check if the Worker sets appropriate CORS headers for the origin

Gotchas

• Always verify the deployed version matches your expected commit. Run wrangler deployments list to confirm your code actually deployed. Cached old versions are a common false trail.
• Don't strip console.log in production builds. You need logs for debugging — if you can't see what's happening, you can't fix what's broken. Keep logging in production, especially during early development.
• Secrets don't copy between environments. Adding a secret to production doesn't add it to staging. After creating a new environment, run wrangler secret list --env <env> to verify ALL required secrets are set.
• Check both .dev.vars AND GitHub Actions secrets. They are independent — a secret in .dev.vars only works locally. GH Actions needs its own secrets configured.
• Deployed URL might not match what you expect. If using custom domains, verify the route pattern in wrangler.toml matches the URL you're testing. Preview deployments use different URLs than production.
• After deploy, wait 30 seconds before testing. Workers edge cache can serve stale responses briefly. If you see old behavior, wait and retry before debugging.