How to set up a merge queue on GitHub
You set up a merge queue on GitHub by installing the Mergify app, committing a small .mergify.yml, and letting Mergify test and merge your pull requests against the real state of main. This guide walks through each step with a config you can copy.
In one paragraph
Install the Mergify GitHub App, add a .mergify.yml that defines a queue and queues approved pull requests, then approve a PR. Mergify rebuilds each PR onto the state main will have at merge time, runs your CI against it, and merges only when it passes. Main stays green even when several people ship at once.
Before you start
You need two things in place:
- A GitHub repository whose CI reports at least one status check on pull requests. If your pull requests already show a green check, you are ready.
- Permission to install a GitHub App on the organization or repository. Installing Mergify takes an admin one click.
Mergify works on top of whatever CI you already run, so there is nothing to rewrite before you begin. For the concept behind what the queue does, the merge queue guide covers the mechanics in depth.
Step 1: Install the Mergify GitHub App
Open the Mergify dashboard and install the GitHub App on the repository you want to queue. Grant it access to that repository. This is the only permission step, and you can start with a single repository while you evaluate.
Step 2: Add a .mergify.yml
Commit this file as .mergify.yml at the root of your repository. It defines one queue and adds approved pull requests to it.
queue_rules:
- name: default
merge_conditions:
- check-success=ci
batch_size: 5
merge_method: squash
pull_request_rules:
- name: Queue approved pull requests
conditions:
- "#approved-reviews-by>=1"
- check-success=ci
actions:
queue:
name: defaultHere is what each part does:
| Key | What it does |
|---|---|
queue_rules | Defines your named queues and how the pull requests in them get tested and merged. |
merge_conditions | The checks a pull request must pass against the queued state before it lands. Replace check-success=ci with the name of your own CI check. |
batch_size | How many pull requests are tested together in a single CI run. Higher batches mean fewer CI runs and a smaller bill. |
merge_method | How the pull request lands on main: merge, rebase, squash, or fast-forward. |
pull_request_rules | The queue action here adds a pull request to the queue once it is approved and its own CI is green. |
Replace check-success=ci with the name of your own CI check before you commit. The queue rules reference lists every key you can set on a queue.
Step 3: Queue your first pull request
Open a pull request and get it approved. The queue rule adds it to the queue as soon as it has an approval and its own CI is green. If you would rather add one by hand while you test, comment @mergifyio queue on the pull request.
Step 4: Watch it merge
Mergify builds a temporary branch that represents main plus the pull requests ahead in the queue plus this one, runs your CI against it, and merges the pull request when the checks pass. If they fail, the pull request leaves the queue and main is never touched. You can follow all of this live from the dashboard.
Tuning the queue
The config above is enough to run a queue. Two settings pay off quickly once your volume grows. Batching tests several pull requests in one CI run and bisects on failure, which cuts most of the queue CI bill. Two-step CI runs light checks on every pull request and saves the full suite for the queue, so you only pay for the heavy run on pull requests that are about to land.
If you are weighing Mergify against the built-in option, Mergify vs GitHub merge queue lays out where the native queue is enough and where it stops being enough.
FAQ
Do I need to change my GitHub Actions workflows?
No. Mergify pushes each candidate to a temporary queue branch and opens a draft pull request for it, so any workflow you already trigger on push or pull_request runs there without edits.
What is the ci in check-success=ci?
It is the name of the status check Mergify waits for. Replace ci with the exact name your CI reports (for GitHub Actions this is usually the job name). You can list several checks under merge_conditions.
Does this replace GitHub's native merge queue?
Yes. Only one queue can own merging into a branch, so you run Mergify or GitHub's native queue per repository, not both. The Mergify vs GitHub merge queue comparison has the side-by-side.
How do I try it without touching my busy repositories?
Install Mergify on one low-traffic repository first, commit the config there, and watch a few pull requests go through before you roll it out more widely.
Can I make hotfixes jump the queue?
Yes. Add a second queue rule with a higher priority, or use a priority rule keyed on a label, so urgent pull requests move to the front. The priority docs cover the syntax.
Last updated: