Mergify Configuration File

Everything you need to know about Mergify configuration file

This page documents the Mergify configuration file: its name, its format, and the data structure schema.

Configuration file name

Mergify applies the following rule to find and use its configuration:

It reads the first file it finds among .mergify.yml, .mergify.yaml, .mergify/config.yml, .mergify/config.yaml, .github/mergify.yml and .github/mergify.yaml, in that order, from the repository root directory.
It reads the file from the default repository branch configured on GitHub (usually main).
It can extend the configuration with another configuration file using the extends keyword; see Extending Configuration Files.

Keep only one of those files in the repository. When a pull request against the default branch adds or modifies one of them and that would leave two or more in place, Mergify does not evaluate the pull request: it reports a failure listing the files it found and which one it reads.

File format

The configuration file uses the YAML format.

The file’s main type is a dictionary and each key of the dictionary configures a different aspect of Mergify:

pull_request_rules configures Workflow Automation;
merge_protections and merge_protections_settings configures Merge Protections;
queue_rules configures the Merge Queue;
merge_queue configures options for the Merge Queue;
priority_rules configures the priorities for the Merge Queue;
scopes configures Merge Queue scopes;
commands_restrictions configures who is able to run commands;
defaults lets you configure default options for various actions;
shared lets you define any YAML payload that can be used using YAML anchors;
extends lets you extend the configuration file by importing another configuration file.

Pull request rules

The top-level key pull_request_rules lets you automate your workflow by writing rules that execute actions. It must be a list of dictionaries with the following keys:

actions

Actions

The actions to perform when the rule matches.

conditions

List of conditions

The conditions that must be met for the rule to be evaluated.

descriptionstring or null·defaultnull#

A description of the rule.

disabled

DisabledDict

or null·defaultnull#

If the rule is disabled, the reason why it's disabled.

namestring#

The name of the rule. This is used when reporting information about a rule. It's not possible to have two rules with the same name.

Example:

pull_request_rules:
  - name: add label when author is jd
    description: jd needs his own label because reasons
    conditions:
      - author = jd
    actions:
      label:
        add:
          - jd

Merge Protections

The top-level key merge_protections lets you protect your merge by adding a list of rules that must match before allowing the pull request to be merged.

descriptionstring or null·defaultnull#

A description of the rule

if

List of conditions

The conditions to check before applying the rule

namestring#

The name of the rule

success_conditions

List of conditions

The conditions to check to validate the rule

The top-level key merge_protections_settings lets you configure the behavior of Merge Protections.

auto_merge_conditions

List of conditions

or null·defaultnull#

Conditions that gate auto-merge. Accepts true as shorthand for unconditional auto-merge, or a list of conditions to restrict the audience. Omit the field to disable auto-merge.

post_commentboolean·defaulttrue#

Whether to post merge protection status comments on pull requests

reporting_methodcheck-runs or deployments·defaultcheck-runs#

The merge protection reporting method

Merge Queue

The top-level key merge_queue lets you configure certain aspects of the merge queue.

checking_labelstring or null·defaultnull#

The label to add on pull requests while the merge queue is checking them, from the moment they enter a batch until they leave the queue. It stays on a pull request parked in a bisection, whose own CI has not started yet.

dequeued_labelstring or null·defaultdequeued#

The label to add on pull requests when they are removed from the merge queue.

max_parallel_checksinteger·default5#

The maximum number of speculative checks allowed to run at the same time. Setting this value to 1 disables speculative checks.

Mergify checks a queued pull request in place, on its own branch and without a draft pull request, when all of these hold:

merge_queue.max_parallel_checks is 1
merge_queue.mode is serial
its queue rule's batch_size is 1 (the max, for a {min, max} range)
its queue rule's max_checks_retries is 0
its queue rule's CI is single-step: merge_conditions are empty or identical to queue_conditions

Even then, a batch built with several pull requests before batch_size was lowered to 1 is checked through a draft pull request.

Otherwise Mergify checks the pull request through a draft pull request, unless it can merge it without one: the pull request is first in the queue, its queue rule's CI is single-step, its merge_method is not merge-batch, and it is already up to date with its base branch or, unless its merge_method is fast-forward, behind it only by queue merges that touched none of its scopes.

modeserial, parallel or isolated·defaultserial#

Defines how the merge queue schedules pull requests.

serial: PRs are tested cumulatively.
parallel: PRs whose scopes don't overlap are tested in parallel.
isolated: PRs are grouped into batches by changed-files similarity; each batch runs as a fully isolated batch, with no dependency on any other batch.

queue_controls_commentboolean·defaulttrue#

When enabled, Mergify renders task-list checkboxes a developer can tick instead of typing @mergifyio queue. The two controls live in different comments.

Queue this pull request: a comment of its own, posted before the pull request is queued.
Requeue this pull request: part of the Merge Queue status comment, after the pull request has left the queue, unless the queue merged it.

queued_labelstring or null·defaultqueued#

The label to add on pull requests when they are added to the merge queue.

reset_on_external_mergenever or always·defaultalways#

Defines the behavior of the merge queue when something is merged outside of the queue. "always": The queue is reset when an external merge is detected. All queued pull requests are re-evaluated to ensure correctness based on the new base branch state. "never": The queue remains unchanged. It does not reset or re-evaluate based on the external merge.

skip_intermediate_resultsboolean·defaultfalse#

Allow PRs to merge even if their own speculative check fails, as long as later downstream checks including them pass and test every scope they touch between them, and schedule conditions are valid.

status_commentsall, outcomes or none·defaultall#

Controls the level of status comments posted on pull requests in the queue.

all: Post comments for all queue events (entering queue, CI progress, outcomes).
outcomes: Only post comments for final outcomes (merged or dequeued with failure reason).
none: Do not post any comments for queue status.

Queue rules

The top-level key queue_rules lets you define the rules that reign over your merge queue.

allow_inplace_checksboolean·defaulttrue·deprecated#

Deprecated: this value is computed automatically.

Mergify checks a queued pull request in place, on its own branch and without a draft pull request, when all of these hold:

merge_queue.max_parallel_checks is 1
merge_queue.mode is serial
its queue rule's batch_size is 1 (the max, for a {min, max} range)
its queue rule's max_checks_retries is 0
its queue rule's CI is single-step: merge_conditions are empty or identical to queue_conditions

Even then, a batch built with several pull requests before batch_size was lowered to 1 is checked through a draft pull request.

allow_queue_branch_editboolean·defaultfalse#

Deprecated: this option is being removed after 2026-12-31, and there is no replacement. Move the work now done on a batch branch onto the pull requests themselves. Once the option is gone, an edited batch branch dequeues the pull requests it carries and reports the edit as a failure, which is the behaviour you get today by leaving this unset.

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.

This option requires merge_method to be merge-batch or fast-forward. Those two merge the batch branch itself, so a commit pushed to it is part of what lands on the base branch; merge, squash and rebase merge each pull request at its own head, which never includes the edit.

Enabling it therefore means the merged content is the batch branch, including commits that were never reviewed as part of any pull request. That is the contract of this option: it exists for batch-level work (a conflict resolution, a migration reorder, a lockfile regeneration) that belongs to no single pull request.

Note also that under these two merge methods Mergify does not merge the pull requests one by one: GitHub marks each embarked pull request as merged only when its head commit is reachable from the new base branch tip, so a pull request whose head no longer matches what was embarked is not shown as merged even though its content landed.

batch_max_failure_resolution_attemptsinteger or null·defaultnull#

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_timeduration·default30 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_sizeinteger or {min, max}·default1#

The number of pull requests per speculative check in the queue. Either a single integer (fixed size, 1-128) or an object {min, max} for dynamic batching: the queue uses min when parallel-check slots are plentiful and grows toward max to keep the backlog at zero.

branch_protection_injection_modequeue, merge or none·defaultqueue#

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 not inject them at all, and requires a merge_bot_account able to satisfy the protections itself.

checks_timeoutduration, auto or null·defaultauto#

The amount of time the merge queue waits for pending checks to return before dequeueing pull requests. This cannot be less than 60 seconds. Defaults to auto, which lets Mergify compute the timeout from the recent CI runtime of this queue (the 95th-percentile runtime with a safety margin). Runs identified as retry reruns or bisection runs are excluded from the calibration; runs whose provenance predates this tracking are kept for compatibility. auto applies no timeout until enough history has been gathered. Set to null to disable the checks timeout entirely.

commit_message_format

CommitMessageFormatModel

or null·defaultnull#

Declarative commit message format configuration. Use this instead of the Jinja2 commit_message_template for the common merge-commit shapes. Mutually exclusive with commit_message_template on the same rule.

commit_message_templatetemplate or null·defaultnull·deprecated#

Template to use as the commit message when using the merge or squash merge method. Deprecated: use commit_message_format instead.

draft_bot_accountBot account or null·defaultnull#

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_retriesinteger·default0#

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_accountBot account or null·defaultnull#

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_methodmerge, rebase, squash, fast-forward or merge-batch or null·defaultnull#

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.

namestring#

Name of the queue rule.

queue_branch_merge_methodfast-forward or null·defaultnull·deprecated#

Deprecated spelling of merge_method: fast-forward. If set to fast-forward, Mergify moves the base branch onto the draft pull request instead of merging the original pull request that has been checked, whatever merge_method is set to. Use merge_method: fast-forward instead.

queue_branch_prefixstring·defaultmergify/merge-queue/#

Prefix for the merge queue branch name. It must start valid git branch names, and cannot start with refs/, which GitHub refuses. Branches under this prefix are eligible for automatic queue branch cleanup.

queue_conditions

List of conditions

The list of conditions that needs to match to queue the pull request.

update_bot_accountBot account or null·defaultnull#

For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. With no update_bot_account, the update goes through GitHub's API as Mergify and impersonates nobody. 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.

Warning: With update_method: rebase and checks run in place, a pull request coming from a fork cannot be rebased on behalf of this account: GitHub refuses an OAuth token on its rebase API for a fork, so it would mean impersonating the account to force-push the contributor's branch. Those pull requests are refused when they are queued. Unset this option to rebase them through GitHub's API as Mergify instead -- except for a fork pull request that changes GitHub Actions workflows or was opened by another App's bot, which GitHub lets Mergify queue in place only with an update_bot_account, or that changes more files than GitHub lists, which Mergify cannot rule out as a workflow change; such a queue has to run its checks on a draft pull request. Or set update_method: merge on a queue that does not merge with fast-forward: such a queue lands by moving the base branch onto this one, so a merge commit is what it exists to keep off it, and it has to run its checks on a draft pull request instead.

update_methodrebase or merge or null·defaultnull#

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 the queue runs its checks in place, a pull request coming from a fork cannot be rebased on behalf of an update_bot_account and is refused -- see that option for the remedy. Without an update_bot_account, the rebase goes through GitHub's API as Mergify, which works on a fork -- except for one that changes GitHub Actions workflows or was opened by another App's bot, which GitHub lets Mergify queue in place only with an update_bot_account, or one that changes more files than GitHub lists, which Mergify cannot rule out as a workflow change. Such a queue has to run its checks on a draft pull request instead.

When null, defaults to merge except if merge_method is fast-forward then it defaults to rebase.

Priority rules

The top-level key priority_rules lets you define the rules that will determine which priority a pull request has when entering your merge queue.

allow_checks_interruptionboolean·defaultfalse#

Allow interrupting the ongoing checks when the pull request entering the queue has a higher priority than the queued one(s). If set to false, a pull request with higher priority will be inserted just after the pull requests that have checks running. Whatever this setting, when every check slot is taken, checks a batch runs ahead of its merge schedule, while that schedule is closed, can give their check slot to a pull request whose merge schedule is open.

conditions

List of conditions

The list of conditions that needs to match to assign priority to the pull request.

namestring#

Name of the rule.

priorityPriority·defaultmedium#

The priority of the pull request.

Defaults

The defaults section provides a means to set configuration values that act as fallbacks for:

Actions executed by both pull request rules and commands
Configuration options for queue rules

Instead of defining the same options repeatedly for different rules, you can specify them once in the defaults section. If a particular option is directly defined under pull_request_rules or queue_rules, it will take precedence; otherwise, the system resorts to the values defined in the defaults section.

defaults:
  actions:
    comment:
      bot_account: Autobot

  queue_rule:
    batch_size: 10

pull_request_rules:
  - name: comment with default
    conditions:
      - label = comment
    actions:
      comment:
        message: I 💙 Mergify

queue_rules:
  - name: default

  - name: default with smaller batch
    batch_size: 2

This configuration is equivalent to:

pull_request_rules:
  - name: comment with default
    conditions:
      - label = comment
    actions:
      comment:
        message: I 💙 Mergify
        bot_account: Autobot

queue_rules:
  - name: default
    batch_size: 10

  - name: default with smaller batch
    batch_size: 2

In the example, the bot_account value is taken from the defaults section, simplifying the pull_request_rules and ensuring consistent behavior across different rules. The same behavior applies for the batch_size option of the queue_rules, the default value of 10 gets applied to the queue rule default but not for the queue rule default with smaller batch, because it already has batch_size: 2.

Shared

You can store anything in the shared key. Its main purpose is to provide a place to put redundant YAML anchors. See Sharing.

Extends

Mergify offers a feature to extend your configuration file by incorporating settings from another repository, aiding in consistency and reducing duplication. This is achieved by using the extends keyword at the top of your configuration file and specifying the source repository. See Extending Configuration Files.

JSON Schema specification

A machine-readable description of the Mergify configuration file format is available as a JSON Schema specification. You can use it to validate configuration files or power editor completion.

You can find the JSON Schema specification for the Mergify configuration here .

Editor support

The schema is listed in the SchemaStore catalog, so editors that read that catalog apply it to your configuration file on their own. VS Code does so with the YAML extension, and JetBrains IDEs do so out of the box. In Neovim, configure the YAML language server with SchemaStore.nvim.

If your editor does not pick the schema up, for example because it does not read the SchemaStore catalog or your file name is not one the catalog lists, point to the schema from the file itself. Editors built on the YAML language server read this comment at the top of the file:

# yaml-language-server: $schema=https://docs.mergify.com/mergify-configuration-schema.json
queue_rules:
  - name: default

In JetBrains IDEs, map the schema URL to your file under Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings instead.

Validation and troubleshooting

Mergify validates your configuration on every push. This section covers how to check your configuration file and track down problems.

Validation

To validate your Mergify configuration file, you can use Mergify’s built-in validation tool. Whenever you push a change to the configuration file, Mergify will automatically validate the configuration and report any errors or warnings in the “Checks” tab of your pull request.

Configuration changed check: the configuration is valid, but pull_request_rules will not be used

If there are any issues with your configuration file, you will receive a detailed description of the problem and guidance on how to fix it.

Sections that are never used

Each product reads its own sections of the configuration, and it only reads them where that product is enabled on the repository. A configuration that defines pull_request_rules without Workflow Automation, queue_rules, priority_rules or merge_queue without the Merge Queue, or merge_protections without Merge Protections is valid, and those sections are never evaluated.

Workflow Automation does not change this for the Merge Queue’s sections: the merge queue only runs where the Merge Queue is enabled. Without it, a queue action reports an error asking you to enable the Merge Queue instead of queueing the pull request, and a pull request already in the queue is removed from it. The queue and dequeue commands need the Merge Queue too.

The configuration check run stays green, since the file really is valid, and it reports which sections will not be used and which product each one is waiting on, with a link to enable it. The simulate command reports the same thing, so you can see it before pushing.

No other top-level section is gated on a product this way, so none of them is ever reported. scopes, shared, extends, commands_restrictions and defaults are read whatever is enabled, even where what they configure belongs to one product, and so is merge_protections_settings, some of which applies outside Merge Protections.

Validate locally with pre-commit

To catch issues before pushing, you can validate your configuration locally using Mergify’s pre-commit hook. Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Mergifyio/mergify-pre-commit
    rev: 1.0.0
    hooks:
      - id: validate-mergify-config

Troubleshooting

If you encounter issues or unexpected behavior with your Mergify configuration file, consider the following troubleshooting steps:

Double-check the file name and location: ensure that your configuration file is correctly named (e.g., .mergify.yml) and is located in the right place. See Configuration File Name for details.
Verify the YAML syntax: confirm that your configuration file follows the proper YAML syntax, including correct indentation, spacing, and structure.
Review your rules and conditions: Make sure that your rules and conditions are correctly defined and accurately reflect your intended workflow.
Check for conflicting rules: examine your rules for any conflicts or overlapping conditions that could cause unintended behavior.
Consult Mergify’s documentation: refer to Mergify’s documentation for guidance on creating and managing your configuration file, as well as understanding the various features and options available to you.

Validating with the CLI

The Mergify CLI can check your configuration file locally before you push, catching errors without waiting for a round-trip to GitHub.

Validate

Check your configuration against the Mergify schema:

mergify config validate

This catches syntax errors, invalid keys, and type mismatches. It detects the configuration file on its own, or reads the path you give it with --config-file.

Simulate

Test your rules against an existing pull request without applying any actions:

mergify config simulate https://github.com/owner/repo/pull/142

Shows which rules would match and what actions Mergify would take. Useful for testing rule changes before merging your configuration update.

Was this page helpful?