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.
06 — Observability: OpenTelemetry → New Relic	The mandatory OTel instrumentation pattern: OTEL_ENABLED toggle, per-env defaults, @microlabs/otel-cf-workers for Workers, browser SDK for Pages SPAs, OTLP-HTTP to New Relic. Required baseline for every new Worker, Pages Function, and SPA.
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.
• Every Worker / Pages site ships with OTel → New Relic behind an OTEL_ENABLED env var (defaults: dev false, stg true, prd true). See 06.

---

Last reviewed: 2026-04-17