Skip to content

SYSTEM Cited by 1 source

Bitbucket Merge Queues

Bitbucket Merge Queues is Atlassian's pre-merge validation queue for Bitbucket Cloud repositories. Its job is to prevent semantic merge conflicts — the failure mode where two PRs each pass branch-level CI cleanly but break main when they land concurrently. It is the canonical Bitbucket instance of the validate against the future state of main pattern.

(Source: sources/2026-04-29-atlassian-inside-atlassians-merge-queues)

Mechanism

Three load-bearing steps:

  1. Queue the PR for a target branch. When branch CI and code review pass, the author clicks Add to merge queue. The PR waits its turn for that target branch.
  2. Validate against the expected future state. For each queued PR, Bitbucket creates a temporary branch named bitbucket-merge-queue-*, merges everything ahead of it in the queue per the configured merge strategy, and runs the merge-queue pipeline against that materialised future state. The pipeline answers: "would main stay green if we landed everything up to and including this PR?"
  3. Merge or eject.
  4. On pass: the PR is merged into the target branch.
  5. On fail: the PR is ejected and left open with the merge-queue results attached; the queue re-evaluates and other queued PRs can proceed. See patterns/eject-failing-pr-keep-queue-running for the canonical recovery discipline.

(Source: sources/2026-04-29-atlassian-inside-atlassians-merge-queues)

Configuration surfaces

  • Build concurrency — how many merge-queue pipelines run in parallel. Jira configures this at 14, sized against ~300+ merges/day throughput.
  • Merge strategy — merge commit / squash merge / rebase merge. Jira uses merge commit (preserves per-PR commit history for forensic debugging). The strategy choice is load-bearing: the temporary merge branch is materialised with this strategy.
  • merge-queues: section in bitbucket-pipelines.yml — lets teams run a different, faster validation suite pre-merge without altering the post-merge pipeline that builds release artefacts. This is the hook that turns systems/bitbucket-pipelines into the merge-queue's execution substrate.
  • Admin controls: reorder PRs (move to the top), drain the queue (stop accepting new PRs), deactivate (pause merges). Used for hot-fix + emergency flow.

(Source: sources/2026-04-29-atlassian-inside-atlassians-merge-queues)

Production outcomes disclosed

From Atlassian's own Bitbucket-Cloud usage, measured across the Jira repository (800+ developers, 300+ merges/day):

Metric Before Merge Queues After Merge Queues
CI failures from semantic merge issues 7–10% near zero
Internal incidents from semantic merge conflicts 3–5/week rare edge cases
Developer-satisfaction on build reliability 70% 82%
End-to-end build time 40 min 35 min

Platform-wide scale: 70+ repos across Jira, Rovo, Trello, and other products; 30,000+ PRs landed through merge queues since the Beta launch in the prior quarter. Jira's Head of Engineering: "our engineers stopped thinking about merging altogether. They just queue and code." (Source: sources/2026-04-29-atlassian-inside-atlassians-merge-queues)

Architectural role

  • Merge-queue pipeline vs post-merge pipeline. These are deliberately different pipelines. The merge-queue pipeline runs a faster validation suite that fits the queue's latency envelope — branch CI equivalent + anything that detects interaction failures with concurrently-queued PRs. The post-merge pipeline (release-artefact build, deploy, e2e) is unchanged.
  • Queue executes on systems/bitbucket-pipelines. Jira's merge-queue pipeline uses three parallel parent-child pipelines (one per product distribution) so the merge-queue validation stays fast even as the number of distribution variants grows. See patterns/parent-child-pipelines-for-ci-parallelism.
  • Temporary-branch discipline. The bitbucket-merge-queue-* namespace is reserved for the system. These branches exist only for the duration of the merge-queue pipeline and are discarded on merge or eject. Git-reference management is not exposed to the user.

Failure-recovery discipline

  • Failed builds eject PRs, not the queue. The canonical design choice: the queue does not stall on a single failure. Ejection preserves authorship context (the PR author still sees the failure on their own PR) and keeps throughput stable.
  • Admins can reorder + drain. For hot-fix flow, admins can move a PR to the top of the queue; for emergency-only flow, admins can drain or deactivate the queue to pause merges entirely.

(Source: sources/2026-04-29-atlassian-inside-atlassians-merge-queues)

What's not disclosed

The [[sources/2026-04-29-atlassian-inside-atlassians-merge-queues|2026-04-29 post]] is an end-user engineering-narrative disclosure, not an internal architecture deep-dive. Specifically not disclosed:

  • Queue-latency envelope (p50/p95 time-from-enqueue-to-merge).
  • Merge-queue pipeline wall-clock (p50/p95).
  • The queue's internal data model / persistence / leader-election / reconciliation with git references.
  • Comparison to peer merge-queue systems (GitHub Merge Queue, Bors-NG, Graphite, Rust bors/homu) — the post reads as a standalone product disclosure.

Peer systems (not disclosed in the source, added for wiki context)

The same three-part shape (queue + future-state pipeline + eject) is the canonical design across multiple merge-queue implementations:

  • GitHub Merge Queue — GitHub's first-party merge queue on github.com repos.
  • Bors-NG — the original open-source "not rocket science" merge queue, inspired by the Rust project's bors / homu lineage.
  • Graphite — merge queue as part of its stacked-PR workflow.
  • Rust bors / homu — the historical lineage, paying the name forward from Knight Rider's BORS to Rust's serialised-merge discipline.

Bitbucket Merge Queues is the Atlassian-first-party instance of this family, with Bitbucket-specific operational primitives (bitbucket-pipelines.yml merge-queues: section, parent-child pipelines, Bitbucket-admin controls) layered on top.

Seen in

Last updated · 433 distilled / 1,256 read