🔀 Merge Queues 🔗
Merge queues prevent merging broken pull requests by serializing their merge. They work like Strict Merge, but also provides some delightful enhancements, like:
faster pull requests merging when multiple pull requests are ready to merge
speculative identification of merge conflicts, tests failure, and continuous integration breakage
different policies for queuing and merging pull requests
When using the
merge action with strict mode, pull requests are updated and
merged one by one serially.
queue action, pull requests are embarked in a merge train. A merge
train consists of two or more pull requests embarked together to be tested
Conditions to get pull requests embarked in the
merge train can be configured
The Merge Train 🔗
When a pull request gets embarked into a merge train, Mergify creates temporary
pull requests to embed multiple pull requests at once. Those temporary pull requests check if the
resulting branch can be merged according to the
For example, let’s say the base branch head commit is
abcdef12 and there are 3 pull
As soon as the 3 pull requests match the conditions for the queue action they get embarked together.
Mergify therefore creates the following pull requests:
Wwith the content of
Xwith the content of
Ywith the content of
The upside of creating multiple pull requests is that continuous integration pipelines can run on all of them in parallel. Currently, Mergify embarks up to 5 pull requests into the merge train.
When the pull request
W matches the
queue_rules, the pull request
is merged and the pull request
W is deleted. The same goes for pull request
B, as well as for the pull request
At this point, let’s say that
B have been merged successfully.
If a 4th pull request
D is created and matches the condition for the queue
action, it is also embarked into the merge train. Since
B have been merged
in the base branch, the new head commit for the base branch is
In that case, Mergify creates a new pull request
Z with the content of
In the case where a new commit is pushed on the base branch, Mergify resets the merge train and starts over the process.
If an embarked pull request doesn’t match the
queue_rules anymore, it
is removed from the merge train. All pull requests embarked after it
are disembarked and re-embarked.
Configuring the Merge Queues 🔗
The merge queues relies on two configuration items: the
queue action. They allow writing complex merge queue
workflows that couldn’t be achieved with the
merge action alone.
queues_rules are used by the
queue action. They define the conditions
to get a queued pull request merged and the configuration of the merge
queue action, a pull request has to match two sets of conditions
to get merged. The first set of conditions described in
allows the pull request to enter in the queue when all conditions match. If
queue action conditions do not match anymore the pull request is
removed from the merge queue. When a pull request is at the top of the queue,
Mergify looks at the seconds set of conditions defined this time in
queue_rules and wait that they all match to merge the pull request.
When multiple queues are defined, they are processed one after the other in the order they are defined in the configuration. When the first pull request in the first queue is waiting to be merged, the remaining queues are blocked.
In the following example, a pull request needs the CI to pass and 2 reviews to
enter the queue. If the
urgent label is set, the pull request enters in the
queue only with 2 reviews, bypassing any pull requests in the default queue.
The urgent queue still ensures the CI passes before merging the pull request.
queue_rules: - name: urgent conditions: - check-success=Travis CI - Pull Request - name: default conditions: pull_request_rules: - name: move to urgent queue when 2 reviews and label urgent conditions: - base=master - "#approved-reviews-by>=2" - label=urgent actions: queue: name: urgent - name: move to default queue when CI passes and 2 reviews conditions: - base=master - "#approved-reviews-by>=2" - check-success=Travis CI - Pull Request actions: queue: name: default
Queue Rule Parameters 🔗
queue_rules takes the following parameter:
The name of the merge queue.
The list of