Auto⁠-⁠Merge

Automatically merge or queue pull requests when all merge protection conditions pass.

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.

Configuration

Unconditional auto-merge

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

Mergify merges the pull request the moment its last success condition is met, whichever one that is. With the merge queue enabled, that moment queues it instead, as long as it also matches the queue's queue_conditions.

Conditional auto-merge

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.

Behavior matrix

`auto_merge_conditions`	Merge queue enabled?	Behavior
`true`	Yes	Every PR is queued once it passes the merge protections and `queue_conditions`
`true`	No	PR is auto-merged once the merge protections pass
List of conditions	Yes	A matching PR is queued once it passes the merge protections and `queue_conditions`
List of conditions	No	PR is auto-merged once both the conditions and the merge protections pass
omitted	—	No automatic action. Merge manually or use the `@mergifyio queue` command

Accepted and rejected values

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.

Examples

Bot-only auto-merge

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

merge_protections_settings:
  auto_merge_conditions:
    - author = dependabot[bot]

Label-gated auto-merge

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

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

Constraints

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.

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: the queue’s queue_conditions decide when it enters the queue, and its merge_conditions when it merges.

Was this page helpful?