---
title: Using Queue Rules
description: 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.).

- 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.

```yaml
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](/merge-queue).

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

| Key name | Value type | Default | Description | Status |
| --- | --- | --- | --- | --- |
| `allow_inplace_checks` | boolean | `true` | 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`) | deprecated |
| `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 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 | `1` | The maximum number of pull requests per speculative check in the queue. Must be between 1 and 128. |  |
| `branch_protection_injection_mode` | `queue` or `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` | template 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. |  |
| `max_checks_retries` | integer | `0` | 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 | `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. 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` or `rebase` or `squash` or `fast-forward` or `merge-batch` or null | `null` | 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 |  |  |  |
| `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`. | deprecated |
| `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 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 | `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`. |  |

## 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](/merge-queue/merge-strategies) guide for a detailed
comparison, including configuration examples and trade-offs.

:::note
  The `fast-forward` method advances the base branch ref directly to the
  tested commit(s) instead of creating a merge via GitHub. It works with both
  single PRs and batches. See
  [Merge Strategies: Fast-Forward](/merge-queue/merge-strategies#fast-forward)
  for details on inplace and batch-PR modes.
:::

:::note
  The `merge-batch` method merges the batch pull request prepared by the
  merge queue directly into the base branch using a merge commit. It requires
  `batch_size > 1`. See
  [Merge Strategies: Merge Batch](/merge-queue/merge-strategies#merge-batch)
  for details.
:::

## 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](/merge-queue/two-step).

You can find more details about the [lifecycle of pull request in the
documentation](/merge-queue/lifecycle#lifecycle-of-a-pull-request-in-the-merge-queue).

## 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](/commands/queue) is required.

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

Example:

```yaml
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](/commands/queue)

- Gate queueing behind an internal custom workflow step