Auto⁠-⁠Merge

Mergify can act on a pull request as soon as all applicable merge protection success_conditions are satisfied. The exact action (merge directly or add to the merge queue) depends on whether the merge queue is enabled for the repository.

Auto-merge is configured with the auto_merge_conditions field under merge_protections_settings. It accepts true for unconditional auto-merge, or a list of conditions to restrict the audience.

Set auto_merge_conditions: true to auto-merge every pull request that satisfies the merge protections:

merge_protections_settings:
  auto_merge_conditions: true

merge_protections:
  - name: require-review-and-ci
    if:
      - base = main
    success_conditions:
      - "#approved-reviews-by >= 1"
      - check-success = ci

Any pull request targeting main with at least one approved review and a passing ci check is automatically merged (or queued if the merge queue is enabled).

Pass a list of conditions to restrict auto-merge to pull requests that match. Only matching pull requests are auto-merged. Other pull requests still need to be merged manually or queued via the @mergifyio queue command.

merge_protections_settings:
  auto_merge_conditions:
    - author = dependabot[bot]

The list accepts the same condition syntax as success_conditions, including nested and, or, and not operators.

auto_merge_conditions accepts:

• true: unconditional auto-merge.

• A list of conditions: conditional auto-merge.

• An empty list ([]): unconditional auto-merge, the same as true. Auto-merge turns on because the field is set, whatever value it holds, and an empty list restricts nothing.

The schema rejects false and any mapping, empty ({}) or not. An explicit null is accepted and means the same as omitting the field: auto-merge stays off.

Auto-merge dependency updates from Dependabot, leaving every other pull request to be merged manually:

merge_protections_settings:
  auto_merge_conditions:
    - author = dependabot[bot]

Auto-merge any pull request that carries the ready-to-merge label:

merge_protections_settings:
  auto_merge_conditions:
    - label = ready-to-merge

queue_rules[].autoqueue is deprecated. The replacement is auto_merge_conditions in merge_protections_settings.

Mergify opens an automatic migration pull request that rewrites the configuration. The translation depends on the shape of the original configuration:

• All queues had autoqueue: true: the migration produces auto_merge_conditions: true. Each queue’s existing queue_conditions still gate routing, so they don’t need to be duplicated.

• One autoqueued queue alongside manual queues: the migration inlines that queue’s queue_conditions into auto_merge_conditions.

• Multiple autoqueued queues alongside manual queues: the migration produces an or over each autoqueued queue’s conditions.

• Autoqueued queue with empty queue_conditions: collapses to auto_merge_conditions: true, since an empty list matches every pull request.

The migration pull request touches only those two keys: it removes autoqueue and writes auto_merge_conditions, leaving the rest of the file, comments included, as you wrote it. If removing autoqueue empties the block that held it, that empty block goes too, so the diff carries no leftover queue_rule:. Queues that were already manual stay manual, and stay reachable via the @mergifyio queue command.

Two shapes are not migrated automatically: Mergify leaves autoqueue in place and says why in the deprecation notice. The first is a repository with Merge Protections disabled, because auto_merge_conditions only takes effect when that product is enabled. Turn it on first; moving the key by hand before that stops pull requests from being queued automatically. The second is a configuration that pulls queue rules in through extends: those rules are not in this file, so Mergify cannot rewrite them from here. Set auto_merge_conditions yourself, then remove autoqueue.

Apply the migration in one step: a configuration that sets auto_merge_conditions while a queue rule still has autoqueue is rejected.

Before:

queue_rules:
  - name: dependencies
    autoqueue: true
    queue_conditions:
      - author = dependabot[bot]
    merge_conditions:
      - check-success = ci

  - name: default
    queue_conditions:
      - check-success = ci

After:

queue_rules:
  - name: dependencies
    queue_conditions:
      - author = dependabot[bot]
    merge_conditions:
      - check-success = ci

  - name: default
    queue_conditions:
      - check-success = ci

merge_protections_settings:
  auto_merge_conditions:
    - author = dependabot[bot]

Merge Protections must be enabled on the repository for auto_merge_conditions to take effect, with or without the merge queue. See Enabling & Configuring Merge Protections.

auto_merge_conditions and queue_rules[].autoqueue cannot be used together. A configuration that sets both is rejected, so remove autoqueue from your queue rules in the same change.

Without the merge queue, auto_merge_conditions only takes effect when at least one merge protection rule applies to the pull request: with no rule whose if conditions match, there are no success_conditions to evaluate and nothing is merged. With the merge queue enabled, a matching pull request is queued whether or not merge protection rules exist, and the queue’s own conditions gate the merge.