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) 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.).
Use autoqueue to automatically add matching PRs to the right queue.

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

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:

Key name	Value type	Default
`allow_inplace_checks`	`boolean`	`true`	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`	`false`
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`	`false`
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.
`batch_max_failure_resolution_attempts`	`integer` or `null`	`null`
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	`30 seconds`
The maximum amount of time to wait before creating a batch when the batch is not full.
`batch_size`	`integer`	`1`
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`	`queue`
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`	`null`
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_template`	template or `null`	`null`
Template to use as the commit message when using the merge or squash merge method.
`draft_bot_account`	`string` or `null`	`null`
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.
`merge_bot_account`	template or `null`	`null`
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. This automatically includes the `queue_conditions`. 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`	`merge`, `rebase`, `squash` or `fast-forward` or `null`	`null`
Merge method to use. If no value is set, Mergify uses the first authorized method available in the repository configuration. `fast-forward` is not supported on queues with `max_parallel_checks > 1`, `batch_size > 1`, or with `allow_inplace_checks` set to `false`.
`name`	`string`
`queue_branch_merge_method`	`fast-forward` or `null`	`null`
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	`mergify/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`	`null`
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`	`rebase` or `merge` or `null`	`null`
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.

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

You can automatically enqueue pull requests that satisfy a queue rule’s queue_conditions by setting the autoqueue flag to true (default is false). When autoqueue: true the pull request is added to the merge queue as soon as it matches queue_conditions. No pull request rule with a queue action or manual queue command is required.

This ensures PRs are enqueued consistently & immediately, reduing latency between validation success and scheduling.

Example:

queue_rules:
  - name: urgent
    autoqueue: true
    queue_conditions:
      - label = urgent
    merge_conditions:
      - check-success = myci

  - name: default
    autoqueue: false
    queue_conditions:
      - check-success = myci
    batch_size: 5

With this configuration, any PR carrying label = urgent is enqueued instantly (even before CI finishes, if you omit that check from queue_conditions), while standard PRs enter only manually after CI succeeds.

Set autoqueue: false (or omit it) if you want enqueueing to be explicit, for example:

Allow contributors to opt‑in manually via the queue command
Gate queueing behind an internal custom workflow step

CI Setup

Test Frameworks Setup

Use Cases

Actions