Deploy a Cloudflare Worker with Wrangler

---
name: deploy-cloudflare-worker-workflow
description: "Validate configuration and build output, run a local or preview check, then deploy only to the named environment and verify it."
---

# Deploy a Cloudflare Worker

## Intended outcome

Publish a Worker to the intended account and environment with a known rollback target.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **Cloudflare Wrangler** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 4.87.0 recorded)
  - Install: `npm install --save-dev wrangler`
  - Authentication: OAuth, API token
  - Minimum permissions: Use an API token limited to the required account, zone, and Worker resources.
- **curl** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 8.7.1 recorded)
  - Install: `brew install curl`
  - Authentication: none, basic, bearer token, client certificate, netrc
  - Minimum permissions: Pass scoped tokens through environment-backed headers and never print request secrets.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- Worker repository
- wrangler configuration
- explicit account and environment
- scoped API token

## Output contract

- Build result
- preview or local check
- deployment ID and URL
- live verification report

## Safe workflow

1. **Inspect configuration** — Read scripts, Worker name, compatibility settings, bindings, and target environment without printing secrets.
   - Input: Repository and Wrangler configuration
   - Output: Deployment target and required bindings
   - Risk: `local-write`
   - Command: `wrangler deploy --dry-run --outdir /tmp/worker-build`
2. **Run a preview check** — Exercise the Worker locally or through a preview path and record expected responses.
   - Input: Built Worker and test requests
   - Output: Preview evidence and outstanding warnings
   - Risk: `read-only`
3. **Deploy and verify** — After approval, deploy to the named environment, save the deployment identifier, and test the live URL.
   - Input: Approved target and scoped token
   - Output: Deployment result and live checks
   - Risk: `remote-write`
   - Command: `wrangler deploy --env production`

## Ask before proceeding

- Deploying to any shared or production environment
- Creating or changing secrets, routes, domains, D1, KV, R2, or other bindings
- Running database migrations

## Rollback

- Record the previous deployment before release
- Use Wrangler’s documented deployment rollback path for the account
- Revert code or configuration and redeploy only after identifying the cause

## Official sources

- [Cloudflare Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/) — Official Wrangler command and configuration documentation for Workers.
- [curl manual](https://curl.se/docs/manpage.html) — Official HTTP options, output handling, retries, and failure semantics.