Merge queue

Connect GitHub, choose repos, run the readiness check, pause the queue, and read the capacity numbers.

What it does

The merge queue merges your pull requests for you, safely. Instead of each pull request being tested alone against an older copy of your main branch, the queue stacks the waiting pull requests together on top of the current main branch, runs your own CI on that combination, and merges each pull request only when the exact combination that will land has passed. If something fails, the queue works out which pull request caused it, sets that one aside with a comment, and carries on with the rest.

You keep your CI, your required checks and your branch rules. The queue adds the ordering, the testing of combinations, and the merging.

The queue builds its test combinations on branches whose names start with mq/. They are deleted when the batch ends.

Connect GitHub to your organization

Only an organization owner or admin can do this. Other members can see the page but not change anything.

  1. In the dashboard, open Merge queue and choose Connect a GitHub account.
  2. GitHub opens. Choose the GitHub organization (or your own account) and the repos the queue may use, then install the App.
  3. GitHub sends you back to the dashboard, and the account shows as connected.

To make sure the right person connects the right account, we check with GitHub that you are an admin of that GitHub organization (or the account's own user). If you are not, the connection is refused and you are asked to have an org admin do this step.

A GitHub account can be connected to one organization at a time. If it is already connected elsewhere, its admins must disconnect it first.

Disconnect removes the account and its repos from the queue. It does not remove the App from GitHub; uninstall it there if you want it gone.

Add a repo and choose its settings

Under your connected account, add a repo by its name (without the owner, for example api) and its base branch (usually main). Each repo and branch is added once. Open the repo to change its settings:

  • Label that queues a pull request. The label you add to a pull request to put it in the queue. The default is merge-when-ready.
  • How pull requests are merged. Merge commit, squash, or rebase.
  • Merge mode. Fast-forward (recommended) lands each tested combination as it was tested. It needs the merge commit method. If you use squash or rebase, choose One at a time, which merges pull requests individually after they pass.
  • Most batches testing at once. A limit on how many batches run your CI at the same time. Leave it empty for no limit. Each batch is a run of your CI.
  • Required checks. The names of the checks that must pass, one per line.
  • Require Greenlight approval before a pull request can merge. Holds each pull request until it has been approved.
  • Only the queue merges to the base branch. Recommended if other people or bots can push to the base branch.

Changing the label, merge method, merge mode or required checks means the readiness check runs again before you can turn the queue on.

The readiness check

The readiness check proves your repo works with the queue before any real pull request depends on it. It pushes a test branch and checks that every required check reports on it. The result shows Passed or Needs attention, when it ran, and a list of anything it found. It also lists anyone else who pushed to the base branch in the last 30 days, since a push you did not expect can break a tested combination.

If you change a setting afterwards, the result is marked as out of date and the check runs again.

Before you turn it on

Because the queue runs your CI on mq/ branches, a few common CI setups need a look first. Under Before you turn it on, an owner or admin ticks each item to confirm it holds for this repo:

  • No deploy job runs on "any branch except main".
  • Restricted contexts do not hide secrets that the queue's test builds need.
  • No workflow is gated on the pipeline event name.
  • Branch filters do not exclude branches that start with mq/.
  • Path filtering compares against the base branch, not the previous commit.
  • "Prevent unregistered users" allows the merge queue bot.
  • GitHub Actions workflows that run on push exclude mq/** branches, or you accept that they run there.
  • Release bots that commit to the base branch go through the queue.

If one does not hold, fix it in your CI first. The queue can be turned on only after the checklist is confirmed and the readiness check has passed.

Turn it on, off, or remove a repo

Once the checklist is confirmed and the readiness check has passed, choose Turn on in shadow mode. In shadow mode the queue builds and tests real combinations and records what it would have merged, but leaves the merging to you. It moves to merging for real after it has seen one passing batch and one failure traced to its cause. Turn off switches the repo off. Remove repo switches it off and takes it off your list.

Merge when ready, and the hold label

Add the queue label (merge-when-ready by default) to a pull request as soon as you open it, even while checks are still running. It means "merge this as soon as it qualifies". A pull request qualifies when:

  • every check on its latest commit has passed, and your required checks have passed;
  • it has the approval you require, if you turned that on;
  • it has no unresolved review threads;
  • it is not a draft, has no merge-queue:hold label, and has no conflict with the base branch.

Being behind the base branch is not a problem. The queue tests the combination itself. A new push means the pull request has to qualify again.

To keep a labelled pull request out of the queue for a while, add the merge-queue:hold label. Remove it to let the pull request back in. Removing the queue label takes it out entirely.

If a pull request conflicts with the base branch or with another pull request in the same batch, the queue leaves it out of that batch and tells you with a comment. It stays labelled and tries again on the next batch. If a pull request breaks the tests, it is set aside with a comment naming the failing checks, and it stays out until you push a new commit and add the label again.

Pause the queue

Pausing stops new batches from starting. It does not merge anything and does not remove anything from the queue.

  • Pause a repo. Open the repo and choose Pause, then Resume when ready. The queue also pauses a repo by itself when something needs a person, for example if your CI does not start for too long or the base branch is red. The reason shows on the page.
  • Pause all repos. On the Merge queue page, an owner or admin can choose Pause all repos to stop every repo in your organization at once, and Resume all to start again.

Pausing and resuming are recorded in your organization's audit log.

The live queue and capacity numbers

Open a repo to see what the queue is doing now: the batches being tested, any pull request being checked on its own to find a failure, the pull requests waiting, and any that were removed with what to do about them. The page refreshes by itself.

The Capacity section shows what your CI lets the queue carry. It appears once the queue has tested a few pull requests; until then it says it is collecting data.

  • Measured ceiling. About how many pull requests per hour the queue can merge with your current CI time, failure rate and batch size. Faster CI, fewer failures and bigger batches raise it.
  • Failure rate. The share of recent pull requests that failed their tests. A small starting allowance keeps the number steady early on.
  • Flaky reruns. How many times a failed run passed when retried. A flaky check counts as passed but costs you CI time.
  • Your CI time. The typical time from the queue starting a batch to your CI's last result, over recent batches.

If the number of pull requests you add per hour gets close to the ceiling, the page warns you before the queue falls behind. If your CI is slow to start builds, the queue tests fewer batches at once, and the page says it is limited by your CI and how many batches it is running at a time. Speeding up how quickly your CI starts, or reducing flaky checks, lifts the limit.

Who can do what

Action Owner or admin Other members
See the queue, repos and capacity Yes Yes
Connect or disconnect a GitHub account Yes No
Add or remove a repo, change settings Yes No
Confirm the checklist, turn a repo on or off Yes No
Pause or resume a repo or the whole organization Yes No

If something looks wrong

  • A pull request is not entering the queue. Check that it has the queue label and none of the blockers above, including the merge-queue:hold label and unresolved review threads.
  • The repo shows paused and you did not pause it. The page gives the reason. Fix it, then choose Resume.
  • The readiness check needs attention. The list under the result says what to fix. The check runs again after you change settings.
  • Capacity says "Collecting data". The queue needs to test a few pull requests before it can measure your CI. This clears on its own.

See Troubleshooting for general help, or contact support from the dashboard.


Build your team.

Your first AI Teammate, working by end of day.

Get product updates by email

What we shipped and what we learned.

Product updates, a few times a quarter. Unsubscribe any time. Privacy

Protected by reCAPTCHA. Privacy · Terms