queue🔗

The queue action moves the pull request into one of the merge queue defined in Queue Rules.

Merge queues prevent merging broken pull requests by serializing their merge. Merging broken pull requests can happen when outdated pull requests are being merged in their base branch.

Why Queues?🔗

To understand the problem queues resolve, imagine the following situation:

The base branch (e.g., main) has its continuous integration testing passing correctly.
A pull request is created, which also passes the CI.

The state of the repository can be represented like this:

While the pull request is open, another commit is pushed to main — let's call it new commit. That new commit can be pushed directly to main or merged from another pull request; it doesn't matter.

The tests are run against the main branch by the CI, and they pass. The state of the repository and its continuous integration system can be now described like this:

The pull request is still marked as valid by the continuous integration system since it did not change. As there is no code conflict, the pull request is considered as mergeable by GitHub: the merge button is green.

If you click that merge button, this is what might happen:

As a new merge commit is created to merge the pull request, it is possible that the continuous integration testing fails. Indeed, the continuous integration did not test the pull request with the new commit added to the base branch. This new commit might have introduced some new tests in the base branch while the pull request was open. That pull request may not have the correct code to pass this new test.

Using Queues🔗

Using a merge queue solves that issue by updating any pull request that is not up-to-date with its base branch before being merged. That forces the continuous integration system to retest the pull request with the new code from its base branch.

If a merge queue were being used in the previous example, Mergify would automatically merge the main in the base branch. The continuous integration system would have rerun and marked the pull request as failing the test, removing it from the merge queue altogether.

When multiple pull requests are mergeable, they are scheduled to be merged sequentially, and are updated on top of each other. The pull request branch update is only done when the pull request is ready to be merged by the engine, e.g., when all the merge_conditions are validated.

That means that when a first pull request has been merged, and the second one is outdated like this:

Mergify will make sure the pull request #2 is updated with the latest tip of the base branch before merging:

That way, there's no way to merge a broken pull request into the base branch.

Configuring the Merge Queues🔗

The merge queues rely on two configuration items: the queues_rules and the queue action.

The queue action places the pull request inside the merge queue: the set of conditions described in the pull_request_rules allows the pull request to enter the queue when all conditions match.

If the 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 set of merge conditions defined in queue_rules and wait until 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 queue_rules list. Queue processing is blocked until all preceding queues are empty.

Mergify always respects the branch protection settings. When the conditions match and the queue action runs, Mergify waits for the branch protection to be validated before embarking and merging the pull request.

Mergify also waits for dependent pull requests to get merged first (see ⛓️ Defining Pull Request Dependencies).

Viewing the Merge Queue🔗

The merge queue can be visualized from your dashboard:

Routing Conditions🔗

The usage of routing_conditions is optional but can be used to have thinner control over routing your pull requests into queues.

routing_conditions are evaluated just before queuing the pull request. Their job is to determine in which queue the pull request must be queued. The pull request will be queued in the first queue matching the routing conditions.

The routing conditions can be expressed using the usual 🎯 Conditions.

You can use routing conditions both with ⚙️ Commands and pull_request_rules.

Example🔗

The following example defines two queues named default and hotfix, and a pull_request_rule. Only the queue hotfix has routing_conditions.

In this case, supposing that the routing_conditions are fulfilled, the command @Mergifyio queue is going to queue the pull request in hotfix. Also, if the pull_request_rule matches, supposing that the routing_conditions are fulfilled, the pull request is going to be queued in hotfix.

Empty routing_conditions are always matching, thus, a pull request will always fallback in a queue with no routing_conditions defined. To avoid a pull request being queued due to the fallback, you need to define routing_conditions for every one of your queues. If no routing_conditions are matching, the pull request will not be queued.

In this case, supposing that the routing_conditions are not fulfilled, the pull request is going to be queued in default.

queue_rules:
  - name: hotfix
    routing_conditions:
      - label=hotfix
    merge_conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request

  - name: default
    merge_conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request

pull_request_rules:
  - name: merge using the merge queue
    conditions:
      - base=main
      - label=queue
    actions:
      queue:

Speculative Checks🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

Merging pull requests one by one serially can take a lot of time, depending on the continuous integration run time. To merge pull requests faster, Mergify queues support speculative checks.

With speculative checks, the first pull requests from the queue are embarked in a merge train and tested together in parallel so they can be merged faster. A merge train consists of two or more pull requests embarked together to be tested speculatively. To test them, Mergify creates temporary pull requests where multiple queued pull requests are merged together.

The upside of creating multiple temporary pull requests is that continuous integration pipelines can run on all of them in parallel. Currently, Mergify embarks up from 1 to 20 pull requests into the merge train (you can set the value with the speculative_checks settings in queue_rules).

In the above example, three pull requests are tested at the same time by the continuous integration system: PR #1, PR #1 + PR #2 and PR #1 + PR #2 + PR#3. By creating temporary pull requests that combine multiple pull requests, Mergify is able to schedule in advance the testing of the combined results of every pull request in the queue.

Those temporary pull requests check if the resulting branch can be merged according to the queue_rules merge conditions. If any of the merge car fails to match the queue_rules merge conditions, the culprit pull request is removed from the queue.

When the pull request PR #1 + PR #2 matches the queue_rules merge conditions, the pull requests PR #1 and PR #2 are merged and the temporary pull request PR #1 + PR #2 is deleted. The same goes for the pull request PR #1 + PR #2 + PR #3 and PR #3.

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.

Warning

With speculative checks, pull requests are tested against the base branch within another temporary pull request. This requires the branch protection settings Require branches to be up to date before merging to be disabled. If you require a linear history, just set the queue option method: rebase.

Batch Size🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

Mergify allows checking the mergeability of multiple pull requests at once using the batch_size option. If set to 3, Mergify will create a draft pull request with the latest version of the base branch and merge the commits of the 3 next queued pull requests.

If the CI validates the draft pull request, Mergify will merge the 3 queued pull requests and close the draft one. If the CI reports a failure, Mergify uses a binary search to build a smaller batch of pull requests to check in order to find the culprit. Once the failing pull request is found, Mergify removes it from the queue. The rest of the queue is processed as usual.

batch_size and speculative_checks can be combined to increase the merge queue throughput.

For example, if your queue is 15 pull requests long and you have speculative_checks set to 3 and batch_size to 5, you'll have 3 draft pull requests of 5 pull requests each being tested at the same time. If your CI time is 10 min, you can merge those 15 pull requests in only 10 minutes.

Warning

With batch mode, pull requests are tested against the base branch within another temporary pull request. This requires the branch protection settings Require branches to be up to date before merging to be disabled. If you require a linear history, just set the queue option method: rebase.

Priority Rules🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

The usage of priority rules is optional but can be used to have thinner control over how your pull requests are ordered inside a queue.

A priority rule applies a priority to a pull request according to the matching conditions you defined. A priority can be a keyword such as low, medium, high or a number (see Priority).

Once a pull request is added to the queue, each priority rule will be evaluated against the priority rules conditions to find in which position the pull request will be added. If there are several rules matching the pull request, the one with the highest priority value will be retained.

The following example defines a queue named default with priority rules controlling the position of the pull requests in the merge queue.

queue_rules:
  - name: default
    merge_conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
    priority_rules:
      - name: hotfix
        conditions:
          - label=hotfix
        priority: high
      - name: low priority
        conditions:
          - label=refactor
        priority: low

pull_request_rules:
  - name: merge using the merge queue
    conditions:
      - base=main
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
    actions:
      queue:
        name: default

Queue Freeze🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

Mergify allows freezing the merge of one or several queues simultaneously to provide maximum control and flexibility on how and when you want the code to be merged.

The freeze feature is available through the Mergify API. A set of API endpoints allows you to create, get, update and delete freezes on your queues.

When a queue is frozen, all the checks and CI configured on the queue rules are still scheduled and triggered; only the merge is blocked. Freezing allows you to continue your work, development, and testing while ensuring that no pull requests will be merged from the queue.

For example, let's say you have three queues, respectively hotfix, default and lowprio, in this order.

You are in the middle of an incident for your project, and want your production branch not to receive anything other than bug fixes. By creating a freeze on the default queue, you are now assured that nothing from this queue — nor the queue after it, lowprio — will be merged.

Meanwhile, you can still merge pull requests pushed to the hotfix queue.

Once your incident is resolved, you can unfreeze the queue default and returns to the previous state.

You can also freeze only one queue without the cascading effect on the queues below.

In the scenario with hotfix, default and lowprio queues, you can freeze the queue default without the cascading effect.

Every pull request that goes through default will not be merged in this configuration. However, without the cascading effect activated on the freeze, every pull request that goes through the queue lowprio will be tested and still be able to be merged.

🚫 Unqueued Pull Request🔗

Mergify removes a pull request from the queue if:

a user has manually unqueued the pull request;
there are CI failures;
there is a CI timeout.

To get the pull request back in the queue, you can either:

retrigger the CI if the problem was due to a CI failure (such as a flaky test) or a timeout;
update the code inside the pull request, which will retrigger the CI
use the requeue to inform Mergify that the CI failure was not due to the pull request itself, but to, e.g., a flaky test.

⛓️ Defining Pull Request Dependencies🔗

You can specify dependencies between pull requests from the same repository. Mergify waits for the linked pull requests to be merged before merging any pull request with a Depends-On: header.

To use this feature, add the Depends-On: header to the body of your pull request:

New awesome feature 🎉

To get the full picture, you may need to look at these pull requests:

Depends-On: #42
Depends-On: https://github.com/organization/repository/pull/123

Warning

This feature does not work for cross-repository dependencies.

🕒 Defining a minimum date to merge🔗

You can specify a date after which you want a pull request to be merged with a Merge-After: header. Mergify will wait for the date and time to be passed before queueing your pull request.

To use this feature, add the Merge-After: header to the body of your pull request, followed by the date, with optionally a time and/or a timezone. If no timezone is specified it will be set to UTC.

Here are the possible formats:

# Year-Month-Day
Merge-After: 2023-04-18

# Year-Month-Day[Timezone]
Merge-After: 2023-04-18[Australia/Sydney]

# Year-Month-Day Hours:Minutes
Merge-After: 2023-04-18 18:20

# Year-Month-Day Hours:Minutes[Timezone]
Merge-After: 2023-04-18 18:20[Australia/Sydney]

For the list of available time zones, see IANA format.

Using Rebase to Update🔗

Using the rebase method to update a pull request with its base branch has some drawbacks:

It doesn't work for private forked repositories.
Every commits SHA-1 of the pull request will change. The pull request author will need to force-push its own branch if they add new commits.
GitHub branch protections of your repository may dismiss approved reviews.
GitHub branch protection of the contributor repository may deny Mergify force-pushing the rebased pull request.
GPG signed commits will lose their signatures.
Mergify will impersonate one of the repository members to force-push the branch as GitHub Applications are not authorized to do that by themselves. If you need to control which user is impersonated, you can use the update_bot_account option. Be aware that the GitHub UI will show the collaborator as the author of the push, while it was actually executed by Mergify.

Merge Queue Pull Requests🔗

The body of draft merge queue pull requests contains, at the end of the body, a YAML document containing various data relative to the PR and what it is testing.

The schema of this YAML document is the following:

pull_requests:
  - number: int

To be more easily found and parsed in the body, you can look for a markdown yaml code-block:

```yaml
---
# data here
...
```

Options🔗

Queue Action🔗

These are the options of the queue action:

Key Name	Value Type	Default	Value Description
`autosquash`	bool	True	This options is relevant only if you do inplace checks and if you use the `rebase` option of the `update_method`. It will automatically squash your commits beginning by `squash!`, `fixup!` or `amend!`, just like the option with the same name when doing a `git rebase`.
`commit_message_template`	Template		Template to use as the commit message when using the `merge` or `squash` merge method. Template can also be defined in the pull request body (see Defining the Commit Message). This option has been moved under the Queue Rules section of the configuration and will be removed from this section in the future.
`merge_bot_account`	Template		Mergify can impersonate a GitHub user to merge pull request. If no `merge_bot_account` is set, Mergify will merge the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission. This option overrides the value defined in the Queue Rules section of the configuration.
`method`	string		Merge method to use. Possible values are `merge`, `squash`, `rebase` or `fast-forward`. `fast-forward` is not supported on queues with `speculative_checks > 1`, `batch_size > 1`, or with `allow_inplace_checks` set to `false`. This option overrides the value defined in the Queue Rules section of the configuration.
`name`	string		The name of the queue where the pull request should be added. If no name is set, `routing_conditions` will be applied instead.
`allow_merging_configuration_change`	bool	false	Allow merging Mergify configuration change.
`require_branch_protection`	bool	true	Whether branch protections are required for queueing pull requests.
`update_bot_account`	Template		For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. If no `update_bot_account` is set, Mergify picks randomly one of the organization users instead. The user account must have already been logged in Mergify dashboard once. This option overrides the value defined in the Queue Rules section of the configuration.
`update_method`	string		`merge` for all merge methods except `fast-forward` where `rebase` is used Method to use to update the pull request with its base branch when the speculative check is done in-place. Possible values: * `merge` to merge the base branch into the pull request. * `rebase` to rebase the pull request against its base branch. Note that the `rebase` method has some drawbacks, see Using Rebase to Update. This option overrides the value defined in the Queue Rules section of the configuration.

Queue Rules🔗

A queue_rules takes the following parameters:

Key Name	Value Type	Default	Value Description
`allow_checks_interruption`	bool	True	Allow interrupting the ongoing speculative checks when a pull request with higher priority enters in the queue. If `False`, pull request with higher priority will be inserted just after the pull requests that have checks running.
`allow_inplace_checks`	bool	True	Allow to update/rebase the original pull request to check its mergeability when first in the queue and not part of a batch or speculative check.
`allow_queue_branch_edit`	bool	false	When creating a branch for a queue, if the code of this branch is edited by an entity external to Mergify, Mergify un-queues all pull requests embarked in the branch and report the issue as a failure. If set to `true`, Mergify will allow such modifications and trust the content of the branch. Make sure only Mergify and your external application are allowed to edit these branches.
`autosquash`	bool	True	This options is relevant only if you do inplace checks and if you use the `rebase` option of the `update_method`. It will automatically squash your commits beginning by `squash!`, `fixup!` or `amend!`, just like the option with the same name when doing a `git rebase`.
`batch_max_failure_resolution_attempts`	int		Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 The number of attempts to resolve a batch failure before unqueueing pull requests. By default, Mergify will attempt to resolve a batch failure by splitting the batch multiple times until it finds the root cause of the failure. You can stop this process earlier by limiting the number of resolution attempts. Setting this to 0 will unqueue all the pull requests from a batch when a batch fails.
`batch_max_wait_time`	Duration	30 s	Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 The time to wait before creating the speculative check temporary pull request. See Speculative Checks.
`batch_size`	int	1	Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 The maximum number of pull requests per speculative check in the queue. Must be between 1 and 20. See Speculative Checks.
`checks_timeout`	Duration		The amount of time Mergify waits for pending checks to return before unqueueing pull requests. This cannot be less than 60 seconds.
`commit_message_template`	Template		Template to use as the commit message when using the `merge` or `squash` merge method. Template can also be defined in the pull request body (see Defining the Commit Message).
`disallow_checks_interruption_from_queues`	list of `queue` names		Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 The list of higher priorities `queue` that are not allowed to interrupt the ongoing checks of this queue.
`draft_bot_account`	string		Mergify can impersonate a GitHub user to create draft pull requests. If no `draft_bot_account` is set, Mergify creates the draft pull request itself. The user account must have already been logged in Mergify dashboard once and have admin, write or maintain permission.
`merge_bot_account`	Template		Mergify can impersonate a GitHub user to merge pull request. If no `merge_bot_account` is set, Mergify will merge the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission.
`merge_conditions`	list of 🎯 Conditions	empty list	The list of `conditions` to match to get the queued pull request merged, In case of speculative merge pull request, the merge conditions starting by `check-` are evaluated against the temporary pull request instead of the original one.
`merge_method`	string	`merge`	Merge method to use. Possible values are `merge`, `squash`, `rebase` or `fast-forward`. `fast-forward` is not supported on queues with `speculative_checks > 1`, `batch_size > 1`, or with `allow_inplace_checks` set to `false`.
`name`	string		The name of the merge queue.
`priority_rules`	list of Priority Rules		Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 The list of `priority_rules` a pull request can match in order to be prioritized when added to a queue. The set of conditions available for `priority_rules` configuration is the same as the usual 🎯 Conditions.
`queue_branch_merge_method`	string	none	If set to `fast-forward`, Mergify will merge the draft pull request instead of merging the original pull request that has been checked. (This only works when the queue action `method` is set to its default `merge`). If GitHub branch protections are enabled, checkout 🛡️ fast-forward merge and GitHub branch protection.
`queue_branch_prefix`	string	mergify/merge-queue/	Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 When creating a draft pull request for a queue, this prefix will be used to name the branch.
`routing_conditions`	list of 🎯 Conditions		The list of `conditions` to match to queue the pull request.
`speculative_checks`	int	1	Open Source Feature 💖 Premium Plan Feature 🦾 Advanced Plan Feature 💪 The maximum number of checks to run in parallel in the queue. Must be between 1 and 20. See Speculative Checks.
`update_bot_account`	Template		For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. If no `update_bot_account` is set, Mergify picks randomly one of the organization users instead. The user account must have already been logged in Mergify dashboard once.
`update_method`	string	`merge` for all merge methods except `fast-forward` where `rebase` is used	Method to use to update the pull request with its base branch when the speculative check is done in-place. Possible values: * `merge` to merge the base branch into the pull request. * `rebase` to rebase the pull request against its base branch. Note that the `rebase` method has some drawbacks, see Using Rebase to Update.

Note

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

Defining multiple queue rules is only available for Premium subscribers.

Priority Rules🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

A priority rule takes the following parameters:

Key Name	Value Type	Default	Value Description
`conditions`	list of 🎯 Conditions		The list of `conditions` to match to apply the priority to the matching pull request inside the queue.
`name`	string		The name of the priority rule.
`priority`	Priority	medium	The value of the pull request priority inside the queue.

Partition Rules🔗

Beta Feature ⚙️

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

Partition rules are used to handle monorepos better. Each partition runs in parallel and includes all the queues defined in the queue_rules. Partitions are independent from each others, meaning that if one merges a pull request, changing the base branch, the others will not be reset, as the change is known by Mergify, and will continue to act independently, as if they were separated repositories.

A pull request can be queued in multiple partitions at the same time. In that case, Mergify will wait for the pull request to be validated in each partition before it can be merged. Even though each partition is independent, they can work together to ensure validation.

If a pull request is queued in several partitions and the queue checks fail in at least one partition, the pull request will be reported as not mergeable. To be merged, the pull request needs to fulfill all the requirements of all the partitions it is queued in.

If your partitions have different criteria for merging pull requests, you can replicate the partition rules logic inside the queue rules merge_conditions and by using the attribute queue-partition-name. For more information, see 🚥 Using partition rules to handle different projects in a monorepo.

A partition rule takes the following parameters:

Key Name	Value Type	Default	Value Description
`name`	string		The name of the partition.
`conditions`	list of 🎯 Conditions		List of `conditions` to determine the partition(s) in which the pull request will be queued. If no partition matches, the pull request will be added to every partition.
`fallback_partition`	bool	false	Allow the partition to work as a `fallback_partition`, see Fallback Partition.

Fallback Partition🔗

If you are in a migration stage towards the use of partition rules, you can use a fallback_partition to handle the pull requests that does not yet have a partition implemented. Thus, the fallback_partition will catch every pull request that does not match any existing partition, in order to not stop your project from performing as usual, while you are designing your rules for your future partitions.

There can only be one fallback_partition in a configuration file, it needs to have no conditions in order to catch every possible pull requests.

partition_rules:
  - name: my fallback partition
    fallback_partition: true

For more information, see 📬 Using a fallback partition to handle your project migration phase to partition rules.

Examples🔗

🐛 Single Queue🔗

A simple usage of the queue is to merge pull requests serially, ensuring they all pass the CI one after the other. The following example defines a queue named default which allows any pull request to be merged once it enters it.

To enter the queue, pull requests need to be based on the main branch, have 2 approving reviews and pass the CI. Once a pull request is in first position in the queue, it will be updated with the latest commit of its base branch.

queue_rules:
  - name: default
    merge_conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request

pull_request_rules:
  - name: merge using the merge queue
    conditions:
      - base=main
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
    actions:
      queue:
        name: default

🚥 Multiple Queues🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

By using multiple queues, it's possible to put some pull requests in a higher priority queue. As queues are processed one after the other, the following example allow to add a label urgent to a pull request so it gets put in the higher priority queue.

queue_rules:
  - name: urgent
    merge_conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request

  - name: default
    merge_conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request

pull_request_rules:
  - name: move to urgent queue when 2 reviews and label urgent
    conditions:
      # A PR can be queued without the CI passing, but needs it to get merged
      - base=main
      - "#approved-reviews-by>=2"
      - label=urgent
    actions:
      queue:
        name: urgent

  - name: merge using the merge queue
    conditions:
      - base=main
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
      - label!=urgent
    actions:
      queue:
        name: default

With such a configuration, a pull request with the label urgent will get into the queue as soon as it's approved by 2 developers but before the CI has even run on it. It will be in front of the default queue. Mergify will update the pull request with its base branch if necessary, wait for the CI to pass and then merge the pull request.

🎲 Speculative Checks🔗

Open Source
Feature 💖

Premium Plan
Feature 🦾

Advanced Plan
Feature 💪

If your continuous integration system takes a long time to validate the enqueued pull requests, it might be interesting to enable speculative checks. This will allow Mergify to trigger multiple runs of the CI in parallel.

In the following example, by setting the speculative_checks option to 2, Mergify will create up to 2 new pull requests to check if the first three enqueued pull requests are mergeable.

queue_rules:
  - name: default
    speculative_checks: 2
    merge_conditions: []

pull_request_rules:
  - name: merge using the merge queue and speculative checks
    conditions:
      - base=main
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
    actions:
      queue:
        name: default

Multiple pull requests can be checked within one speculative check by settings batch_size.

For example, by settings speculative_checks: 2 and batch_size: 3, Mergify will create two pull requests: a first one to check if the first three enqueued pull requests are mergeable, and a second one to check the three next enqueued pull requests.

queue_rules:
  - name: default
    speculative_checks: 2
    batch_size: 3
    merge_conditions: []

pull_request_rules:
  - name: merge using the merge queue and speculative checks
    conditions:
      - base=main
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
    actions:
      queue:
        name: default

🤙 Get notified when a pull request is unexpectedly unqueued🔗

- name: Notify author on queue failure
  conditions:
    - 'check-failure=Queue: Embarked in merge train'
  actions:
    comment:
      message: >
        Hey @{{ author }}, this pull request failed to merge and has been
        dequeued from the merge train.  If you believe your PR failed in
        the merge train because of a flaky test, requeue it by commenting
        with `@mergifyio requeue`.
        More details can be found on the `Queue: Embarked in merge train`
        check-run.

To receive mentions on Slack, you can then use the native GitHub integration.

🛡️ `fast-forward` merge and GitHub branch protection🔗

If GitHub branch protections are enabled, fast-forward requires some additional configuration in branch protection settings, you also need to allow Mergify to bypass the required pull requests to merge.

../../_images/mergify-required-pull-request.png

🚥 Using partition rules to handle different projects in a monorepo🔗

If a pull request contains a modification on any file in the folder projectA/ it will be added in the partition projectA, if it contains a modification on any file in the folder projectB/ then it will be added in the partition projectB, if it contains a modification in both folder projectA/ and projectB/, then it will be added in both partitions.

If none of the two partitions rules matches, then the PR will be added in both partitions. The queue_rules will still determine in which queue in the partition(s) the pull request will be added in.

Here is a table representing the partition and queues with the code below:

projectA	projectB
hotfix	hotfix
default	default

shared:
    priority_rules: &priority_rules
        - name: hotfix PR detected
          conditions:
            - label=hotfix
          priority: high
        - name: lowprio PR detected
          conditions:
            - author=dependabot[bot]
          priority: low

pull_request_rules:
   - name: queue PR with queue label
     conditions:
       - label=queue
     actions:
       queue:

partition_rules:
  - name: projectA
    conditions:
      - files~=^projectA/

  - name: projectB
    conditions:
      - files~=^projectB/

queue_rules:
  - name: hotfix
    priority_rules: *priority_rules
    routing_conditions:
      - label=hotfix
    merge_conditions:
      - or:
        - and:
          - queue-partition-name=projectA
          - check-success=ciA
        - and:
          - queue-partition-name=projectB
          - check-success=ciB

  - name: default
    priority_rules: *priority_rules
    merge_conditions:
      - or:
        - and:
          - queue-partition-name=projectA
          - check-success=ciA
        - and:
          - queue-partition-name=projectB
          - check-success=ciB

📬 Using a fallback partition to handle your project migration phase to partition rules🔗

If a pull request contains a modification on any file in the folder projectA/ it will be added in the partition projectA, if it contains a modification on any file in the folder projectB/ then it will be added in the partition projectB, if it contains a modification in both folder projectA/ and projectB/, then it will be added in both partitions.

If none of the two partitions rules matches, then the PR will be added in the fallback partition. The queue_rules will still determine in which queue in the partition(s) the pull request will be added in.

In the usual context of use, when a pull request is manually merged, Mergify will reset every queue and partition. But during your project migration phase towards the implementation of partition rules, you might need to manually merge some pull requests. Then, in a context where your are using a fallback partition, Mergify will detect the manually merged pull request and evaluate it against the current partition rules. If the pull request matches an existing partition, it will be reset, otherwise, only the fallback partition will be reset.

Here is a table representing the partition and queues with the code below:

projectA	projectB	fallback
hotfix	hotfix	hotfix
default	default	default

shared:
    priority_rules: &priority_rules
        - name: hotfix PR detected
          conditions:
            - label=hotfix
          priority: high
        - name: lowprio PR detected
          conditions:
            - author=dependabot[bot]
          priority: low

pull_request_rules:
   - name: queue PR with queue label
     conditions:
       - label=queue
     actions:
       queue:

partition_rules:
  - name: fallback
    fallback_partition: true

  - name: projectA
    conditions:
      - files~=^projectA/

  - name: projectB
    conditions:
      - files~=^projectB/

queue_rules:
  - name: hotfix
    priority_rules: *priority_rules
    routing_conditions:
      - label=hotfix
    merge_conditions:
      - or:
        - and:
          - queue-partition-name=projectA
          - check-success=ciA
        - and:
          - queue-partition-name=projectB
          - check-success=ciB
        - and:
          - queue-partition-name=fallback
          - check-success=ciFallback

  - name: default
    priority_rules: *priority_rules
    merge_conditions:
      - or:
        - and:
          - queue-partition-name=projectA
          - check-success=ciA
        - and:
          - queue-partition-name=projectB
          - check-success=ciB
        - and:
          - queue-partition-name=fallback
          - check-success=ciFallback

queue🔗

Why Queues?🔗

Using Queues🔗

Configuring the Merge Queues🔗

Viewing the Merge Queue🔗

Routing Conditions🔗

Example🔗

Speculative Checks🔗

Batch Size🔗

Priority Rules🔗

Queue Freeze🔗

🚫 Unqueued Pull Request🔗

⛓️ Defining Pull Request Dependencies🔗

🕒 Defining a minimum date to merge🔗

Using Rebase to Update🔗

Merge Queue Pull Requests🔗

Options🔗

Queue Action🔗

Queue Rules🔗

Priority Rules🔗

Partition Rules🔗

Fallback Partition🔗

Examples🔗

🐛 Single Queue🔗

🚥 Multiple Queues🔗

🎲 Speculative Checks🔗

🤙 Get notified when a pull request is unexpectedly unqueued🔗

🛡️ fast-forward merge and GitHub branch protection🔗

🚥 Using partition rules to handle different projects in a monorepo🔗

📬 Using a fallback partition to handle your project migration phase to partition rules🔗

🛡️ `fast-forward` merge and GitHub branch protection🔗