Skip to main content

​
Deployment Runbook

This runbook covers staging and production deployments for a Factory app Worker.

​
Environment overview

EnvironmentWrangler envDomain
Local dev(none)localhost:8787
Stagingstaging{app}-staging.{account}.workers.dev
Productionproduction{app}.thefactory.dev
For the Factory Cloudflare account, {account} is always adrper79, so staging-style Worker URLs use {app}-staging.adrper79.workers.dev and direct production Worker URLs use {app}.adrper79.workers.dev unless a custom domain is documented in Service Registry. Secrets are managed per-environment via Wrangler secrets and are never stored in source.

​
Prerequisites

  • CF_API_TOKEN with Workers Deploy permission (this is the canonical name used by all Factory workflows)
  • CLOUDFLARE_ACCOUNT_ID for the target account
  • GitHub Actions: both secrets must be set at the repo level
⚠️ Token naming note: Factory workflows use CF_API_TOKEN (not CLOUDFLARE_API_TOKEN). Both are set as GitHub secrets on every app repo so tools that look for either name will work. When writing new workflows, always reference secrets.CF_API_TOKEN. See GitHub Secrets Runbook for full details.

​
1. Deploy to staging

​
Ready-to-deploy checklist

  • npm run typecheck passes with zero errors.
  • npm run lint passes with --max-warnings 0.
  • npm test passes for touched packages/apps.
  • npm run build passes when the package/app defines a build script.
  • Required Wrangler secrets are set for the target Worker.
  • Service Registry has the canonical Worker name, URL, critical endpoints, consumers, bindings, and secrets.
  • Any Worker rename followed the rename protocol before deployment.
  • Rollback path is known before production deploy begins.
wrangler deploy --env staging

​
Via GitHub Actions

Push to the staging branch, or trigger the deploy-staging workflow manually: 
gh workflow run deploy.yml -f environment=staging

​
2. Smoke-test staging

BASE=https://{app}-staging.{account}.workers.dev

# Health check
curl -s $BASE/health | jq .

# Auth round-trip (requires a valid JWT_SECRET to be set on staging)
TOKEN=$(curl -s -X POST $BASE/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"test@example.com","password":"..."}' | jq -r .token)

curl -s $BASE/api/me -H "Authorization: Bearer $TOKEN" | jq .

​
Per-app smoke tests

After every staging or production deploy, test the Worker-specific critical_endpoints listed in Service Registry, not only /health. Minimum smoke set:
  1. GET /health returns 200.
  2. Public read endpoints return the documented status.
  3. Protected endpoints return 401 or 403 without credentials, not 5xx.
  4. Authenticated operator endpoints return the expected status with valid credentials.
  5. Mutating endpoints reject invalid payloads with structured 4xx errors.
For the shared video Workers, the Phase 0 smoke set is:
  • schedule-worker: /health, /jobs/pending, /jobs/:id, /jobs, /migrate.
  • video-cron: /health, /trigger.
The repeatable automation for this smoke set is the Smoke Video Phase 0 GitHub Actions workflow. It verifies public health, anonymous 401 responses, idempotent migration, a synthetic schedule-to-failed audit flow, and the authenticated video-cron trigger path. Do not mark deployment complete until the expected HTTP status codes are observed directly.

​
3. Deploy to production

wrangler deploy --env production

​
Via GitHub Actions

Merge to main. The deploy.yml workflow runs automatically:
  1. typecheck job must pass.
  2. deploy job runs wrangler deploy.
  3. Cloudflare returns a deployment URL — verify /health.

​
4. Rollback

Before rollback, confirm whether rollback is safe:
  1. Schema changed? Prefer a forward fix if rollback would strand new rows or break migrated data.
  2. Consumers changed? Roll back consumers first if the Worker URL or response contract changed.
  3. Secrets changed? Verify the previous deployment can still read required Wrangler secrets.
  4. Money movement involved? Pause payouts/webhooks before rollback and reconcile after recovery.
  5. Telemetry changed? Keep correlation IDs stable so incident review remains traceable.

​
Instant rollback (last deployment)

wrangler rollback --env production

​
Rollback to a specific deployment

# List recent deployments
wrangler deployments list --env production

# Rollback to a specific ID
wrangler rollback <deployment-id> --env production

​
5. Check deployment status

wrangler deployments list --env production
Or view in the Cloudflare dashboard: Workers & Pages → → Deployments.

​
6. Monitor after deploy

  • Check Sentry for new error spikes (first 15 minutes are critical).
  • Check PostHog for any drop in key events (page views, conversions).
  • Check Cloudflare Analytics for error rate; alert threshold is > 1% 5xx.

​
Rollout strategy

Factory Workers are instant-deploy (no canary by default). If the change is high-risk, use a Cloudflare Workers gradual rollout via the dashboard, splitting traffic 10% → 50% → 100% over 30-minute windows.

​
CI/CD pipeline overview

push to main
  └─ typecheck (tsc --noEmit)
       └─ passes ──► deploy (wrangler deploy --env production)
                          └─ Cloudflare returns deployment ID