Mergify Configuration File

Everything you need to know about Mergify configuration file

The Mergify configuration file is an essential component of using our platform effectively. This document will provide a comprehensive overview of the file, including its name, format, and the data structure schema.

Configuration File Name

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

It reads the file named .mergify.yml, or, as a fallback, .mergify/config.yml or .github/mergify.yml from the repository root directory.
It reads the file from the default repository branch configured on GitHub — usually main.
It can extends the configuration by another configuration using the keyword extends — see “extending the configuration file”.

File Format

The configuration file uses the YAML format, which is both human-readable and machine-parsable. YAML is easy to read and edit, making it a popular choice for configuration files.

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

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

Pull Request Rules

The top-level key pull_request_rules allows to automate your workflow by writing rules that execute actions. It must be a list of dictionary 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.

description#string or null·defaultnull

A description of the rule.

disabled#

DisabledDict

or null·defaultnull

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

name#string

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 allows to protect your merge by adding a list of rules that must match before allowing the pull request to be merged.

description#string or null·defaultnull

A description of the rule

if#

List of conditions

The conditions to check before applying the rule

name#string

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 allows to configure the behavior of Merge Protections

auto_merge#boolean·defaultfalse·deprecated

Automatically merge or queue PRs when all merge protection conditions pass. Deprecated: use auto_merge_conditions.

auto_merge_conditions#true or

List of conditions

·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_comment#boolean·defaulttrue

Whether to post merge protection status comments on pull requests

reporting_method#check-runs or deployments·defaultcheck-runs

The merge protection reporting method

Merge Queue

The top-level key merge_queue allows to configure certain aspect of the merge merge queue.

dequeued_label#string or null·defaultdequeued

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

max_parallel_checks#integer·default5

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

mode#serial or parallel·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.

queued_label#string or null·defaultqueued

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

reset_on_external_merge#never 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_results#boolean·defaultfalse

Allow PRs to merge even if their own speculative check fails, as long as a later downstream check including them passes and schedule conditions are valid.

status_comments#all, 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 allows to define the rules that reign over your merge queue.

allow_inplace_checks#boolean·defaulttrue·deprecated

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)

allow_queue_branch_edit#boolean·defaultfalse

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·defaultfalse·deprecated

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. Deprecated: use merge_protection_settings.auto_merge_conditions instead.

batch_max_failure_resolution_attempts#integer 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_time#duration·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_size#integer·default1

The maximum number of pull requests per speculative check in the queue. Must be between 1 and 128.

branch_protection_injection_mode#queue, 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 disable branch protections. This mode is supported only on queues using a merge_bot_account with admin rights.

checks_timeout#duration or null·defaultnull

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_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_template#template or null·defaultnull

Template to use as the commit message when using the merge or squash merge method.

draft_bot_account#template 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_retries#integer·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_account#template 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_method#merge, 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.

name#string

Name of the queue rule.

queue_branch_merge_method#fast-forward or null·defaultnull·deprecated

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.

queue_branch_prefix#template·defaultmergify/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·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. 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·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 null, defaults to merge except if merge_method is fast-forward then it defaults to rebase.

Priority Rules

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

allow_checks_interruption#boolean·defaulttrue

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.

conditions#

List of conditions

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

name#string

Name of the rule.

priority#high, medium or low or integer·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

For those interested in a more detailed and machine-readable description of the Mergify configuration file format, a JSON Schema specification is available. This specification can help you understand the structure of the configuration file and can be used to generate client libraries, server stubs, or API documentation.

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

Validation and Troubleshooting

When working with Mergify’s configuration file, it’s essential to validate and troubleshoot any issues that may arise. Ensuring that your configuration file is error-free and well-structured can help prevent unexpected behavior and maintain a smooth workflow.

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.

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. Be sure to address any errors or warnings to ensure optimal performance and avoid potential issues.

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.

By following these troubleshooting steps, you can effectively identify and resolve any issues with your Mergify configuration file, ensuring a smooth and efficient automation process for your repository.

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 reads .mergify.yml, .mergify/config.yml, or .github/mergify.yml from the current directory.

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?

Edit this page on GitHub

Scopes

CI Setup

Test Frameworks Setup

Compare Tools

Actions

Reference

Mergify Configuration File

Everything you need to know about Mergify configuration file

Configuration File Name

File Format

Pull Request Rules

Merge Protections

Merge Queue

Queue Rules

Priority Rules

Defaults

Shared

Extends

JSON Schema Specification

Validation and Troubleshooting

Validation

Validate Locally With Pre-Commit

Troubleshooting

Validating with the CLI

Validate

Simulate