2026-07-16, Bitbucket Pipelines as the primary Workers CI/CD for Bitbucket teams
2026-07-16
Section titled “2026-07-16”Status
Section titled “Status”Proposed
Context
Section titled “Context”Part of the engineering organization keeps Bitbucket as the primary code repository. Those teams are building Cloudflare Workers as part of the ongoing move to the edge. Cloudflare’s native CI/CD, Workers Builds, integrates only with GitHub and GitLab; its Git integration does not support Bitbucket, and Cloudflare’s own guidance routes non-GitHub, non-GitLab providers to external CI/CD.
Three paths were considered:
| Option | Source of truth | Native dashboard builds | Moving parts | New failure modes |
|---|---|---|---|---|
| A. Bitbucket Pipelines plus Wrangler | Bitbucket | No | Pipeline YAML plus scoped token | None beyond a normal pipeline |
| B. Mirror to GitHub or GitLab, use Workers Builds | Bitbucket, deploy from mirror | Yes | Pipeline or mirror plus token plus mirror remote | Mirror lag, failed mirror push |
| C. Separate CI runner (Jenkins, self-hosted GitLab CI) | Bitbucket | No | Same as A on other infra | Only worth it if that infra already exists |
Decision
Section titled “Decision”Adopt Option A, Bitbucket Pipelines running Wrangler against a scoped Cloudflare API token, as the primary CI/CD path for Bitbucket-hosted Workers.
The pipeline reproduces the platform’s existing gate sequence, three-environment model, staging soak, and rollback exactly. It keeps Bitbucket authoritative and adds no new failure surface beyond a standard pipeline. Option B is documented as the alternative for a team that specifically needs Cloudflare-native pull-request preview builds, and would be adopted per team, not globally.
Consequences
Section titled “Consequences”- Bitbucket-hosted Workers deploy from
bitbucket-pipelines.yml, not from a developer machine in steady state, matching the QA and Deployment SOP. - Each such repository holds a scoped
CLOUDFLARE_API_TOKEN(Workers Scripts:Edit plus specific zones, plus Secrets Store:Edit where a Worker binds a stored secret) andCLOUDFLARE_ACCOUNT_IDas Bitbucket variables. Production credentials are scoped to the Production deployment environment. - Runtime secrets remain in Cloudflare Secrets Store, bound by reference. The pipeline never runs
wrangler secret put. - Production deploys are tag-triggered and gated behind a manual trigger and an environment reviewer restriction.
- On ratification, this content is promoted and cross-linked into
system-infrastructure/cloudflare/workers/as a sibling of the QA and Deployment SOP. - A wording conflict in
CLAUDE.md§3.2 (“deploys never from GitHub Actions”) is noted for reconciliation; the QA and Deployment SOP is authoritative per the repo precedence rule.