Options
Three viable paths. Bitbucket Pipelines keeps Bitbucket authoritative and is the recommendation. Mirroring to GitHub or GitLab buys the native dashboard at the cost of a second remote.
Option A: Bitbucket Pipelines plus Wrangler (recommended)
Section titled “Option A: Bitbucket Pipelines plus Wrangler (recommended)”Bitbucket stays the source of truth. A bitbucket-pipelines.yml at the repo root runs the gate sequence and calls wrangler deploy on the branches and tags you choose. Cloudflare authenticates with a scoped API token stored as a secured Bitbucket variable.
What you own: the pipeline YAML, the API token, and its rotation.
What you get: a pipeline structurally identical to the platform’s GitHub Actions stub, running entirely inside Bitbucket. Deployment tracking and production gating come from Bitbucket Deployments.
What you give up: the Cloudflare dashboard build history, automatic pull-request preview builds, and framework auto-configuration that Workers Builds gives GitHub and GitLab users. None of these are load-bearing for the platform’s current flow.
This is the least moving parts and the smallest conceptual gap from what the team already runs. The rest of this project documents Option A end to end.
Option B: Mirror Bitbucket to GitHub or GitLab, use Workers Builds
Section titled “Option B: Mirror Bitbucket to GitHub or GitLab, use Workers Builds”Keep Bitbucket as the day-to-day repository but push-mirror each repo to GitHub or GitLab, and point Workers Builds at the mirror.
What you own: the mirror plumbing. Either a Bitbucket Pipelines step that pushes to the mirror remote on every change, or GitLab’s native pull-mirroring which can pull from an external Bitbucket repo on a schedule.
What you get: the full native experience. Dashboard build logs, per-branch and per-pull-request builds, automatic project configuration, and the git commit metadata Workers Builds injects as build environment variables.
What you give up: simplicity. Engineers now reason about two remotes, and a mirror lag or a failed mirror push becomes a class of deploy failure that does not exist in Option A. Secrets and branch protection must be reasoned about on the mirror, not only on Bitbucket.
Choose this only if the native dashboard tooling is worth the second remote. For most teams it is not.
Option C: A separate CI runner
Section titled “Option C: A separate CI runner”If the organization standardizes on a separate CI system (self-hosted GitLab CI, Jenkins, or similar), the same Wrangler-plus-token pattern runs there. This is Option A with a different runner and is only worth it when that infrastructure already exists for other reasons. It is out of scope here.
Comparison
Section titled “Comparison”| Dimension | A: Bitbucket Pipelines | B: Mirror to GitHub/GitLab |
|---|---|---|
| Source of truth | Bitbucket | Bitbucket, deployed from mirror |
| Cloudflare dashboard builds | No | Yes |
| PR preview builds | Manual (branch pipeline) | Automatic |
| Moving parts | Pipeline YAML plus token | Pipeline or mirror plus token plus mirror remote |
| New failure modes | None beyond a normal pipeline | Mirror lag, failed mirror push |
| Setup effort | Low | Medium |
| Ongoing maintenance | Token rotation | Token rotation plus mirror health |
Recommendation
Section titled “Recommendation”Adopt Option A. It keeps Bitbucket authoritative, adds no new failure surface, and reproduces the platform’s existing gate sequence and environment model exactly. Revisit Option B only if a team specifically needs Cloudflare-native pull-request preview builds. See the decision record.