Setting Up a Merge Queue
Implement your first merge queue.
Mergify's Merge Queue is a powerful feature that helps you streamline and manage your pull request (PR) merging process more efficiently.
The Merge Queue works by ensuring each PR meets all defined conditions before it's merged. It checks for PR status, branch conditions, approval reviews, and other set criteria, ensuring that your main branch is always stable and free of bugs that might occur due to unreviewed code. Furthermore, by managing PRs queue, Mergify eliminates the need for manual tracking and merging, freeing up your team to focus on what's essential — building quality software.
In this guide, we'll walk you through the process of setting up your first Merge Queue, explain how to add PRs to it, and show you how to configure the conditions that the PRs must meet before being merged. Whether you're new to Mergify or looking to make your process more efficient, this guide will give you the knowledge you need to leverage the power of Merge Queue.
Mergify provides a default merge queue named
default for every repository as
soon as you set up Mergify. This queue works out-of-the-box and uses your
repository's branch protection
defined in GitHub.
For instance, if you have branch protection rules that require passing CI
checks before merging, the
default merge queue respects these rules. It means
Mergify will only merge pull requests that pass these checks and are in the
Understanding this default queue is essential as it forms the basis of how Mergify handles your pull requests, ensuring a streamlined and orderly merge process.
For more details about merge queues and their functions, you can refer to our merge queue introduction.
To have a more refined control over the PRs entering the merge queue and when
they get merged, you can set up
queue_rules in your Mergify configuration
file. These two constructs allow you to define custom conditions that should be
met before a PR is added to the queue (
queue_conditions) and when it can be
Here is an example of how you can use
queue_rules:- name: defaultqueue_conditions:- check-success = mycijob- "#approved-reviews-by >= 1"
In this example, a PR can enter the
default queue when the CI named
has passed, and if the pull request has been approved by at least one
contributor. If that's the not the case, the PR won't get queued.
The default for Mergify is to allow any PR to be queued.
merge_conditions defines the condition required to get a PR merged once
it has entered the queue. Mergify injects all branch protection
defined by GitHub, so there's no need to repeat them. You can however, add more
if you want, or only rely on Mergify for setting up those conditions:
queue_rules:- name: defaultqueue_conditions:- check-success = mycijob- "#approved-reviews-by >= 1"merge_conditions:- check-success = mycijob-extra
If a PR stops matching its
queue_conditions, it will be removed from the
queue. That means there is no need to repeat the
queue_conditions in the
merge_conditions as they are implicit.
Once you have your merge queue rules set up, you can manually add a PR to the
merge queue. To do this, use the
queue command. This will
add your PR to the specified merge queue, or to the merge queue matching the
Remember, the PR will only be merged once the conditions defined in the
merge_conditions field are met.
If you prefer, you can ask Mergify to automatically queue pull requests that are ready using workflow automation.
After you've added Pull Requests to your merge queue, you will want to monitor its status to understand the progression of your PRs. This can be done directly from the Mergify dashboard. In the "Repository" section, you will see a "Merge Queues" tab. Clicking on it will show you the current state of your merge queue.
Here, you can view all the PRs in the queue and their current statuses. PRs
that are waiting for their
merge_conditions to be met are marked as pending,
while those that have met all their
queue_conditions are displayed in the
queue and will be merged when they reach the top of the queue.
Remember, the PRs in the queue are ordered based on their addition time. The PR added first will be merged first after all its conditions are met. You can modify the order of the pull request inside a queue using priorities.
Congratulations, you've just set up your first Merge Queue with Mergify! You're now armed with a powerful tool to automate and streamline your PR merging process, reducing the potential for conflicts and ensuring your main branch is always in a consistent, deployable state.
However, setting up a basic merge queue is just the beginning. Mergify's powerful and flexible configuration system enables you to tailor your merge queues to your specific needs.
For further exploration and inspiration, here are some additional resources and use cases that you might find useful:
- Using priorities to order your pull requests;
- Using multiple queues;
- Speeding up your merge queue with speculative checks;
- Saving CI time with batches;
- Delaying checks at merge time;
- Splitting repositories into partitions (monorepo support).
Remember, the possibilities with merge queues are limited only by your imagination. Happy merging!