Skip to content
compiler.dev
Start free

What Is a Merge Queue in GitHub?

Last updated

A merge queue is a GitHub feature that lines up approved pull requests and tests each one against the latest base branch plus the changes queued ahead of it, merging only when those checks pass. It stops two individually green pull requests from breaking the main branch together.

How it works

Without a queue, a pull request is tested against the base branch as it was when the last commit was pushed. If another pull request merges first, your green result is out of date. With a queue, when you click "Merge when ready", GitHub creates a temporary branch (a merge group) containing the base branch, the PRs ahead of you and your PR. It runs required checks on that combined state. If they pass, the PR merges. If they fail, it is removed from the queue and later entries are rebuilt without it.

The queue can batch several pull requests into one merge group to save CI time. You set the merge method, group size and minimum wait in the branch protection or ruleset settings.

Example

Required status checks must run for the merge_group event, or they never report and the queue stalls:

on:
  pull_request:
  merge_group:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

The complete setup, including rulesets, is in GitHub merge queue explained.

Common mistakes

  • Missing the merge_group trigger. The most common cause of a PR stuck at "waiting for status". Add it to every workflow that provides a required check.
  • Slow CI. Each queued PR waits for checks, so a 20 minute pipeline makes a long queue. Speed matters more here; see slow CI.
  • Path filters on required checks. If a required job is skipped by a filter, it never reports on the merge group. Use a final "gate" job.
  • Assuming it works on all plans. Availability depends on plan and repository type. Check GitHub's current docs.
  • Running expensive suites twice. Tests run on the pull request and again in the queue. Move heavy end-to-end tests to the queue only.

Because queued runs pile up, a concurrency group should not cancel merge_group runs. Cancel superseded PR runs, never queue runs.

Related terms

FAQ

Is a merge queue the same as auto-merge?

No. Auto-merge merges once checks pass on the PR's own commit. A merge queue tests the combined result before merging.

Do flaky tests matter more with a queue?

Yes. A flaky failure ejects a pull request and restarts the entries behind it. See flaky tests.

Can I skip the queue for hotfixes?

Admins can bypass branch protections if the ruleset allows it. Use this sparingly.

Related