Skip to content

CONCEPT Cited by 1 source

Merge queue

Definition

A merge queue is a queue of accepted pull requests that are validated against the would-be-future state of the target branch before being merged. It replaces the "green PR = merge now" discipline of branch-protection with a queue + dedicated-pipeline shape, turning the merge into a managed background task rather than a coordinated event the author has to time.

The load-bearing reframing: the queue answers

"would the target branch still be green if we landed everything up to and including this PR?"

instead of branch CI's less-useful

"does this PR work on its own?"

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

Shape

Every merge-queue implementation shares the same three-part shape:

  1. Queue: accepted PRs (branch CI + review green) enter a queue for the target branch.
  2. Future-state pipeline: for each PR, the system creates a temporary branch that merges everything ahead of it per the configured strategy, and runs a pipeline against that future state.
  3. Merge or eject: on pass, merge; on fail, eject the PR and let the queue continue.

This three-part shape is canonicalised architecturally in patterns/validate-against-future-state-of-main.

What problem it solves

Merge queues defend against semantic merge conflicts — PRs that pass branch-level CI in isolation but break main when combined with other concurrent green merges. At scale (hundreds of merges/day with hundreds of developers) this failure mode becomes the dominant CI-reliability problem — Atlassian's Jira repo disclosed 7–10% of CI failures attributable to semantic merge conflicts before merge queues (Source: sources/2026-04-29-atlassian-inside-atlassians-merge-queues).

What it is NOT

  • Not a serial-merge discipline. A queue with build-concurrency=1 would be a serialised merge — the queue adds parallelism via batched future-state validation so the queue drains faster.
  • Not branch protection. Branch protection rules (required reviews + required status checks) are orthogonal. Branch protection ensures each PR is reviewed + green against the current target; a merge queue ensures each PR is green against the future target.
  • Not a rollback mechanism. Merge queues prevent the broken merge from landing in the first place. When the queue ejects a PR, main was never actually touched — the revert / rollback machinery downstream of the merge is unused.
  • Not a CI-speed improvement primarily. Atlassian's disclosed build-time improvement on Jira was modest (40 min → 35 min). The load-bearing outcome is reliability — semantic-merge failures near-zeroed out, incident rate collapsed, developer satisfaction lifted. Build-time is a secondary bonus.

Operational configuration

Real merge-queue deployments expose a small set of operational knobs:

  • Build concurrency — how many future-state pipelines run in parallel. Atlassian's Jira repo uses 14 for 300+ PRs/day.
  • Merge strategy — merge commit / squash merge / rebase merge. Determines how the temporary future-state branch is materialised and how main's history looks after merge. Atlassian's Jira uses merge commit (preserves per-PR commits for forensic debugging).
  • Merge-queue pipeline definition (distinct from post-merge pipeline) — the pre-merge validation suite that has to fit the queue's latency envelope. Atlassian exposes this via the merge-queues: section in bitbucket-pipelines.yml.
  • Admin controls — reorder (move a hot-fix to top of queue), drain (stop accepting new PRs), deactivate (pause merges entirely).

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

Implementations

  • systems/bitbucket-merge-queues — Atlassian's Bitbucket Cloud implementation; canonical Atlassian instance on the sysdesign-wiki.
  • GitHub Merge Queue — GitHub's first-party merge queue on github.com repos (not ingested on the wiki yet; noted here for orientation).
  • Bors-NG — open-source merge queue, the "not rocket science" lineage named after Rust's bors.
  • Graphite — merge queue as part of its stacked-PR workflow.
  • Rust bors / homu — the original lineage.

All of these share the three-part queue + future-state-pipeline + eject shape. The differentiation is in which repo host they integrate with + which CI substrate runs the future-state pipeline.

Scale envelope (where the pattern pays off)

Merge queues are operationally expensive (each PR runs an extra pipeline, queue + future-state logic has to be administered, temp branches generate git-reference churn). They pay off when:

  • Merge frequency is high enough that concurrent merges are the common case, not the exception (Atlassian's Jira: 300+/day).
  • PR-set interacts: refactors + new-feature PRs + dependency-upgrade PRs routinely touch code each other indirectly depends on.
  • main-green is load-bearing for other humans: broken main stops everyone else's local branch rebases, breaks local dev environments, and compounds firefighting.

Below these thresholds, branch protection + rebase-required is adequate. Above them, it stops scaling.

Seen in

Last updated · 433 distilled / 1,256 read