Lorixen.
EN

Two passing pull requests broke main? Use a merge queue

Short answer: Two pull requests can each pass every check on their own and still break your main branch once both are merged, because neither was ever tested with the other's changes. GitHub's merge queue fixes this by testing each queued pull request on top of the latest main branch plus everything ahead of it in the queue, and merging only when that combination passes. To use it, turn on "Require merge queue" for the branch and make your CI run on the merge_group event, or the queue will wait forever for checks that never start.

How "both green" still breaks main

A typical story: one developer renames a function and updates every place it's called. Another developer, working at the same time, adds a new call to the old name. Both pull requests pass CI against the version of main they started from. Both get approved and merged within the hour. Main now fails to build, and the next deploy either stops or, worse, ships something broken.

Nothing was careless. The problem is that each check tested a combination of code that would never exist. The code that actually landed on main, with both changes together, was never tested before it got there.

The slow fix: require branches to be up to date

GitHub's branch protection has long offered "Require branches to be up to date before merging". It forces a pull request to include the latest main and pass checks again before merging. That closes the gap, but on a busy repository it creates a race: every merge makes every other open pull request out of date, so authors keep updating branches and waiting for CI, and whoever is slowest loses.

GitHub describes the merge queue as giving the same benefit without requiring authors to update their branch and wait for checks before trying to merge. It suits branches that take many pull requests a day from different people.

How a merge queue works

Once a pull request has passed its required checks and reviews, someone with write access adds it to the queue instead of merging it directly. Then:

  1. The queue builds a temporary branch containing the latest main, any pull requests already ahead in the queue, and this pull request.
  2. It asks your CI to run the required checks on that temporary branch.
  3. If they pass, the changes merge into main in first-in, first-out order.
  4. If they fail, or there's a conflict with main, the pull request is removed from the queue and its timeline shows why. Others behind it are regrouped without it.

GitHub lists the reasons a pull request can be dropped: failing CI for its merge group, a timeout waiting for CI, someone removing it, or a branch protection failure that couldn't be resolved automatically.

Setting it up on GitHub

Check availability. GitHub says merge queues are available in public repositories owned by an organization, and in private organization repositories on GitHub Enterprise Cloud. A private repository on a personal account won't have the option.

Turn it on. A repository admin enables "Require merge queue" in the branch protection rule or ruleset for main. GitHub notes it can't be used with branch protection rules that use wildcards in the branch name pattern, so protect main by its exact name.

Update your CI. This is the step most teams miss. If you use GitHub Actions for required checks, add merge_group as a trigger alongside pull_request:

on:
  pull_request:
  merge_group:

Without it, GitHub warns, checks aren't triggered for queued pull requests, the required status is never reported, and the merge fails. If you use another CI service, configure it to run on pushes to branches starting with gh-readonly-queue/, the temporary branches the queue creates.

Settings worth choosing deliberately

When you enable the queue you can set:

  • Merge method: merge, rebase or squash for queued pull requests. Pick the one your team already uses.
  • Build concurrency: how many merge groups can run CI at once. More is faster but uses more CI minutes.
  • Only merge non-failing pull requests: if unticked, a pull request that failed a check can still merge as part of a group whose final combined build passed. GitHub suggests this can help with intermittent test failures, but it's usually better to fix those tests.
  • Status check timeout: how long to wait for CI before treating checks as failed. Set it a little above your normal build time.
  • Merge limits: minimum and maximum pull requests merged together, plus a wait time. A maximum is useful if every merge to main triggers a deploy and you don't want too many changes going out at once.

Things to watch after switching

Check that anything triggered by pushes to main, such as deploys, still behaves as expected now that merges arrive from the queue. If you build preview environments for every branch, exclude the temporary queue branches so you don't spin up previews nobody will look at. Tell the team the new habit: approve, then add to the queue, rather than pressing merge.

An illustrative example

A web agency in Austin maintains a booking platform for several clients from one repository. Twice in a month, main broke after two approved pull requests merged close together, and a client's release slipped. The team enables the merge queue on main, adds merge_group to their test workflow, sets squash merges and a maximum group size, and limits concurrency to fit their CI budget. Pull requests now wait a little longer in the queue, but main stays deployable.

FAQ

Do small teams need a merge queue?

If only one or two people merge a day, "require branches to be up to date" may be enough. The queue pays off when merges overlap often.

Does the queue replace code review?

No. Reviews and required checks still apply before a pull request can join the queue.

Can urgent fixes skip the line?

GitHub's documentation describes an option to jump to the top of the queue. Use it sparingly and only for genuine emergencies, so the rest of the queue keeps its order.

What if our tests are flaky?

Flaky tests will remove good pull requests from the queue. Treat a merge queue as a reason to fix them.

If your main branch keeps breaking after "safe" merges and you want your workflow and CI set up to prevent it, tell us how your team merges today.

Sources

WhatsAppBook a call