---
title: Using Queue Rules
description: Learn how to implement queue rules and route your pull requests.
---

import OptionsTable from '../../../components/Tables/OptionsTable';

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:

<OptionsTable def="QueueRuleModel" />

## Merge Method

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

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 draft-PR modes.
:::

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