Merge Queue

June 3, 2026 · View on GitHub

English | 中文

Merge Queue is suitable for teams with frequent PR merges and a busy main branch.

The problem it solves is: each PR passes CI individually, but when multiple PRs are merged sequentially, the combined result might break the main branch.

The Problem

Suppose two PRs are both based on the same main:

main: A
PR 1: A + B
PR 2: A + C

Both PR 1 and PR 2 pass CI when run individually.

But after PR 1 is merged first, what PR 2 actually needs to merge into is:

A + B + C

This combined result has not been verified, and it could break the main branch.

Suitable Scenarios

  • A large number of PRs are merged into the main branch every day
  • The main branch must remain stable
  • CI is fully automated
  • The team can accept queuing for merges
  • The repository has already enabled required status checks

Unsuitable Scenarios

  • Very few PRs
  • CI is very slow and lacks resources
  • The team does not yet have stable basic checks
  • The main branch is not required to be deployable at any time

Prerequisites for Use

Before enabling Merge Queue, confirm that:

  • CI can handle merge queue-related events
  • Required checks names are stable
  • The team understands the behavior once a PR enters the queue
  • Emergency hotfixes have a clear processing path

Implementation Key Points

If using GitHub Actions, critical workflows must respond to the merge_group event:

on:
  pull_request:
  merge_group:

Merge Queue is best enabled after branch protection and required checks are stable. If CI is slow or there are many flaky tests, the queue will amplify these issues.

Shopify's public practices are a useful reference: as team size grows, passing CI for a single PR is no longer enough; the combined result after queuing must also be verified, and the queue status, failure reasons, and retry paths must be presented to developers. The core value of Merge Queue is exposing the combined risk before merging into the main branch.

If the team doesn't yet have stable CI, required checks, branch protection, and hotfix paths, fill in the basic capabilities first before enabling Merge Queue. For more case comparisons, see Big Tech Engineering Practice Decision Map.

Further Reading