View as Markdown

Using Queue Rules

Learn how to implement queue rules and route your pull requests.

In larger projects with a high volume of pull requests, managing merges can become complex. This is where Mergify’s multiple queue rules feature becomes a game-changer: it enables you to have finer control over the merge process by categorizing pull requests based on any criteria you define.

Queue rules let you organize your PR merge process into separate templates, each with its own merge configuration.

With queue rules, you can:

  • Define multiple queues for different categories of PRs (e.g. dependencies vs. features).

  • Control merge methods (merge, squash, rebase, fast-forward) per queue.

  • Adjust batching behavior (batch size, max wait time).

  • Apply custom conditions for queuing and merging (labels, branch targets, CI checks, file paths, etc.).

Configuring Queue Rules

Section titled Configuring Queue Rules

Multiple queue rules are defined under the queue_rules key in your configuration file. Each rule needs a unique name and can have different configurations.

queue_rules:
  - name: urgent
    # Can be queued early if the PR has the urgent label
    queue_conditions:
      - label = urgent
    # Still requires CI to pass before merge
    merge_conditions:
      - check-success = myci


  - name: default
    # Requires CI both for queueing and merging
    queue_conditions:
      - check-success = myci

Configuration Options

Section titled Configuration Options

The top-level key queue_rules allows you to define the rules that reign over your merge queue.

Here are all the available fields you can configure for a queue rule:

allow_inplace_checks#boolean·defaulttrue·deprecated

Deprecated: this value is computed automatically. In-place checks are enabled only when:

  • max_parallel_checks == 1
  • every queue has batch_size == 1
  • every queue CI is single-step (no extra merge_conditions; either empty or identical to queue_conditions)
allow_queue_branch_edit#boolean·defaultfalse

When creating a branch for a queue, if the commits of this branch are edited by an entity external to Mergify, Mergify dequeues 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.

autoqueue#boolean·defaultfalse·deprecated

When set to true, automatically add a pull request to the queue when it matches the queue conditions. When false, the pull request must be manually queued. Deprecated: use merge_protection_settings.auto_merge_conditions instead.

batch_max_failure_resolution_attempts#integer or null·defaultnull

The number of attempts to resolve a batch failure before dequeueing 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 dequeue all the pull requests from a batch when a batch fails.

batch_max_wait_time#duration·default30 seconds

The maximum amount of time to wait for additional pull requests before processing a batch that hasn't reached batch_size. The timer starts when the first pull request enters the batch. If batch_size is reached before this time expires, the batch processes immediately. This does not enforce a minimum delay between batches.

batch_size#integer·default1

The maximum number of pull requests per speculative check in the queue. Must be between 1 and 128.

branch_protection_injection_mode#queue, merge or none·defaultqueue

Branch protections conditions injection mode to use.

  • queue will inject branch protections conditions as required conditions for queuing and merging pull requests.
  • merge will inject branch protections conditions as required conditions only for merging pull requests.
  • none will disable branch protections. This mode is supported only on queues using a merge_bot_account with admin rights.
checks_timeout#duration or null·defaultnull

The amount of time the merge queue waits for pending checks to return before dequeueing pull requests. This cannot be less than 60 seconds.

commit_message_format#

CommitMessageFormatModel

or null·defaultnull

Declarative commit message format configuration. Use this instead of the Jinja2 commit_message_template for the common merge-commit shapes. Mutually exclusive with commit_message_template on the same rule.

commit_message_template#template or null·defaultnull

Template to use as the commit message when using the merge or squash merge method.

draft_bot_account#template or null·defaultnull

Mergify can impersonate a GitHub user to create its 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.

max_checks_retries#integer·default0

Number of times Mergify will retry failed CI checks before removing the pull request from the queue. On each retry, the draft pull request is recreated to trigger a fresh CI run. This is useful for handling flaky CI. When set to a value greater than 0, in-place checks are disabled and a draft pull request is always created. Set to 0 (default) to disable retries.

merge_bot_account#template or null·defaultnull

Mergify can impersonate a GitHub user to merge pull requests. If no merge_bot_account is set, Mergify merges 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

The list of conditions to match to get the queued pull request merged. In case of draft pull request, the merge conditions for checks are evaluated against the temporary pull request instead of the original one.

merge_method#merge, rebase, squash, fast-forward or merge-batch or null·defaultnull

Merge method to use. If no value is set, Mergify uses the first authorized method available in the repository configuration.

Additionally, merge-batch merges the draft pull request prepared by the merge queue using a merge commit. This requires batch_size > 1.

name#string

Name of the queue rule.

queue_branch_merge_method#fast-forward or null·defaultnull·deprecated

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 merge_method is set to merge.

queue_branch_prefix#template·defaultmergify/merge-queue/

Prefix for the merge queue branch name

queue_conditions#

List of conditions

The list of conditions that needs to match to queue the pull request.

update_bot_account#template or null·defaultnull

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 uses the pull request author 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#rebase or merge or null·defaultnull

Method to use to update the pull request with its base branch when the 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.

When null, defaults to merge except if merge_method is fast-forward then it defaults to rebase.

Merge Method

Section titled Merge Method

The merge_method option controls how pull requests are merged into the base branch. Accepted values are merge, rebase, squash, fast-forward, and merge-batch.

Each method produces a different git history shape. See the Merge Strategies guide for a detailed comparison, including configuration examples and trade-offs.

Queue vs. Merge Conditions

Section titled Queue vs. Merge Conditions

  • queue_conditions → Requirements for a PR to be accepted into the queue. Example: a label, a CI check, or a branch filter.

  • merge_conditions → Requirements for a PR to be merged once it reaches the front of the queue. Example: all CI checks passed, required approvals.

This separation lets you schedule PRs early (e.g. based on labels) while still enforcing stricter checks before merge. This can be used to implement two-step CI.

You can find more details about the lifecycle of pull request in the documentation.

Auto‑Queueing Pull Requests

Section titled Auto‑Queueing Pull Requests

Control auto-queueing with auto_merge_conditions in merge_protections_settings. It accepts true for unconditional auto-merge, or a list of conditions to restrict the audience.

Was this page helpful?

Edit this page on GitHub