Skip to content

Adventive — Cloudflare Workers SOP

Owner: Adventive Platform Engineering Scope: All Cloudflare Workers deployed under the Adventive Cloudflare account (and any Adventive-managed subsidiary accounts). Status: Living document. Propose changes via pull request against this folder.

Purpose

This Standard Operating Procedure (SOP) defines how Adventive designs, names, deploys, secures, and maintains Cloudflare Workers. It exists so that any engineer — current or future, internal or contracted — can:

  1. Look at a Worker in the dashboard and immediately know what it does, who owns it, and what environment it serves.
  2. Spin up a new Worker from a blessed template in minutes, with our defaults baked in.
  3. Ship to production with confidence that secrets aren't leaking, tests pass, and rollback is possible.
  4. Understand which Workers are mission-critical and what the redundancy and disaster-recovery posture is for each.

Contents

Section What it covers
01 — Naming Conventions How every Worker, route, KV namespace, D1 database, R2 bucket, and secret is named. Includes worked examples for all four project categories.
02 — Wrangler Configuration Standard The canonical wrangler.toml layout. What fields are required, optional, and forbidden.
03 — Secrets & Security Policy What counts as a secret, where secrets live, the mandatory pre-commit and pre-deploy scan, and the incident response path if a leak is discovered.
04 — QA & Deployment Process The gate sequence every build must pass before reaching production — including the promote-through-environments flow and rollback procedure.
05 — Resiliency & Disaster Recovery Tiers of criticality, what redundancy each tier requires (replication, failover, backups), and how to document a Worker's DR posture.
worker-stub/ Ready-to-clone TypeScript Worker project (browse on GitHub). Copy this folder, rename, and you have a Worker that already complies with every section above.

How to use this package

Starting a new Worker:

# From your local machine, with the Cloudflare SOP checked out:
cp -R workers-sop/worker-stub/ ~/code/<new-project-name>/
cd ~/code/<new-project-name>/
# Then follow worker-stub/README.md — it walks through renaming, bindings, and first deploy.

Auditing an existing Worker: Read sections 01–05 in order and mark any deviations. File a ticket to bring it into compliance, or document why the deviation is accepted (and get the Platform lead's sign-off).

Changing the SOP itself: These documents are the source of truth. If reality diverges, update the document — don't let the SOP rot. All changes go through pull request review, same as code.

Quick reference — the one-liners

  • Naming pattern: {scope}-{category}-{project}[-{service}]-{env} — e.g. adv-svc-turnstile-proxy-prd
  • Environments: dev, stg, prd (three, no more, no less)
  • Categories: int (internal), site (website), svc (microservice/API), cli (client build)
  • Secrets: Never in wrangler.toml, never in git. Use wrangler secret put or dashboard-managed secrets only.
  • Every build runs: lint → typecheck → unit tests → secret scan → dry-run deploy → smoke test. In that order.
  • Every production deploy is preceded by: a successful staging deploy with the same commit SHA, observed for ≥ the soak window defined in section 04.

Last reviewed: 2026-04-17