What Is a Merge Queue?

flowchart LR
  A["PR approved<br/>+ PR CI ✓"] --> B["Enter queue"]
  B --> C["Build test branch:<br/>main + queued PRs + this PR"]
  C --> D{"Run queue CI"}
  D -->|pass| E["Merge ✓<br/>main stays green"]
  D -->|fail| F["Reject<br/>main untouched"]

  style E fill:#E6F8F2,stroke:#1CB893,color:#1A1D24
  style F fill:#FDECEA,stroke:#E53935,color:#1A1D24

A pull request goes through four stages once it enters the queue.

1. Entering the queue

The PR has been approved and PR-level CI has passed. The author (or an automation rule) adds it to the queue. The queue checks the PR is eligible (required checks present, no draft, branch is up to date enough), assigns a position based on priority and arrival time, and records the current state of the target branch.

2. Building the test branch

The queue creates a temporary branch that represents "what main will look like after this PR merges." This is the key insight. The test branch contains every commit on main, every PR ahead in the queue (when speculative checks are enabled, meaning the queue tests PRs in parallel rather than one at a time), and the PR's own changes merged in.

3. Running CI

The queue triggers CI on the test branch. This is often called "queue CI" to distinguish it from the CI that ran on the PR itself. The queue waits for all required checks to complete and watches their statuses.

On GitHub Actions, queue CI runs on the merge_group event. If your existing workflows trigger on push or pull_request, adding merge_group is a one-line change. No workflow rewrite required.

A common pattern is two-step CI: lightweight checks on the PR (lint, unit tests, type check) and the full expensive suite (E2E, integration, browser tests) only in the queue. You only pay the full CI cost on PRs that are actually about to land.

4. Merging or failing

If CI passes, the queue merges the PR using your configured strategy (merge commit, squash, rebase, or fast-forward) and notifies the next PR in line. If CI fails, the PR is removed from the queue, main stays untouched, and the author gets a comment explaining why. PRs behind the failed one are automatically re-evaluated, since they were being tested against a state that will never exist.

What this costs you in time and CI

Queue CI adds one CI run of latency per PR. With a 30-minute pipeline and a serial queue, a PR queued at 9:00 merges around 9:30. Two features change that math:

• Batching groups multiple PRs into a single CI run. Batches of 4 mean roughly 25% as many CI runs, at the cost of one extra bisection round when a batch fails. Most teams cut their queue CI bill by 50 to 75% with this alone.
• Speculative checks run multiple PRs in parallel instead of one at a time. Per-PR latency drops back toward the single-CI floor even at 50+ PRs a day. The cost is wasted CI when an early speculation fails and the PRs behind it have to restart.

Most teams turn both on. The combined math gets you the throughput of a parallel queue at the cost of a serial one.

See the Mergify merge queue docs for the configuration syntax that controls each of these stages.

At any given moment, the queue holds several PRs in different states. A simplified view:

Each PR's "tested against" base includes every PR ahead of it. That is how the queue guarantees PRs are tested against the future state of main, not the past.

When a PR fails mid-queue (say #102), the queue removes it and re-tests everything behind it. PR #103 was being tested against main + #101 + #102. That world no longer exists, so the queue rebuilds the test branch as main + #101 and re-runs CI. Manual queue management is the bug a merge queue exists to fix; you should never have to do this by hand.

GitHub launched its native merge queue in 2023. It works for the basic case: PRs queue up, get tested via the merge_group event in Actions, and merge in order. For small teams on a single repo, it can be enough.

It runs into limits quickly. There is no parallel scoping (a CSS PR waits behind every other PR), no batching with automatic bisection, no two-step CI pattern, no priority queues, and the analytics are minimal. There has also been at least one well-publicized incident where the native queue silently reverted merged code. For monorepos, regulated environments, or teams over about 30 engineers, the gaps start to bite.

The dedicated merge queue tools (Mergify, Trunk, Aviator, and a handful of others) cover those gaps with different tradeoffs. The most common comparison is the one against GitHub's native queue:

Comparison

Mergify vs GitHub merge queue

Side-by-side: parallel queues, batching, two-step CI, monorepo support, queue analytics. Where GitHub's queue is enough and where it stops being enough.

Read the comparison →

For the other paid options, see Mergify vs Trunk or Mergify vs Aviator.