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.

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

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:

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:

Key nameValue type
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.

descriptionstring

The description of the rule. This is not used directly by Mergify.

conditionslist of condition

A list of conditions that must match against the pull request for the rule to be applied.

actions

action

A dictionary made of actions that will be executed on the matching pull requests.

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

The top-level key queue_rules allows to define the rules that reign over your merge queues.

Key nameValue typeDefault
namestring

The name of the merge queue.

queue_conditionslist of condition

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

require_branch_protectionbooleantrue

Whether branch protections are required for queueing pull requests.

merge_conditionslist of condition

The list of conditions to match to get the queued pull request merged. This automatically includes the queue_conditions. In case of speculative merge pull request, the merge conditions starting by check- are evaluated against the temporary pull request instead of the original one.

branch_protection_injection_modequeue, merge or none

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

Allow interrupting the ongoing checks when a pull request with higher priority enters in the queue. If false, pull request with higher priority will be inserted just after the pull requests that have checks running.

allow_inplace_checksbooleantrue

Allow to update/rebase the original pull request to check its mergeability when first in the queue and not part of a batch or speculative check.

allow_queue_branch_editbooleanfalse

When creating a branch for a queue, if the code of this branch is edited by an entity external to Mergify, Mergify un-queues 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.

batch_max_failure_resolution_attemptsnumber or null

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

30 s

The maximum amount of time to wait before creating a batch when the batch is not full.

batch_sizenumber1

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

checks_timeout

duration

or null

The amount of time Mergify waits for pending checks to return before dequeueing pull requests. This cannot be less than 60 seconds.

commit_message_template

template

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

disallow_checks_interruption_from_queues

list of string

The list of higher priorities queue that are not allowed to interrupt the ongoing checks of this queue.

draft_bot_accountstring

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.

merge_bot_account

template

Mergify can impersonate a GitHub user to merge pull requests. If no merge_bot_account is set, Mergify will merge the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission.

merge_method

merge method: merge, squash, rebase or fast-forward

Merge method to use. fast-forward is not supported on queues with speculative_checks > 1, batch_size > 1, or with allow_inplace_checks set to false.

priority_ruleslist of priority rule

The list of priority rules a pull request can match in order to be prioritized when added to a queue. The rule with the highest priority value wins.

queue_branch_merge_methodnone or fast-forwardnone

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 the queue action merge_method is set to its default merge.

queue_branch_prefixstringmergify/merge-queue/

The prefix used to name the branch of draft pull requests.

speculative_checksnumber1

The maximum number of checks to run in parallel in the queue. Must be between 1 and 20.

update_methodmerge or rebase

Method to use to update the pull request with its base branch when the speculative 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.
update_bot_account

template

For rebasing branches, Mergify might have 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 author of the PR. The user account must have already been logged in Mergify dashboard once. For update_method: merge this option will be ignored in order for Mergify to not reset the merge queue, because of the merge commit done has a person instead of a bot.

The top-level key partition_rules allows to split your repositories into independent partitions. This is especially useful when using a monorepo with the merge queue.

Key nameValue type
namestring

The name of the partition.

conditionslist of condition

List of conditions to determine the partition(s) in which the pull request will be queued. If a pull request matches no partition, it is added to the fallback partition if defined, otherwise it is added to every partition.

fallback_partitionboolean

Allow the partition to work as the fallback partition.

The defaults section provides a means to set configuration values that act as fallbacks for actions executed by both pull request rules and commands. 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, it will take precedence; otherwise, the system resorts to the values defined in defaults.

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

This configuration is equivalent to:

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

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.

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

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.

For those interested in a more detailed and machine-readable description of the Mergify configuration file format, an OpenAPI 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 OpenAPI specification for the Mergify configuration here .

Validation and Troubleshooting

Section titled 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.

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.

Mergify configuration check

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.

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

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

  2. Verify the YAML syntax: confirm that your configuration file follows the proper YAML syntax, including correct indentation, spacing, and structure.

  3. Review your rules and conditions: Make sure that your rules and conditions are correctly defined and accurately reflect your intended workflow.

  4. Check for conflicting rules: examine your rules for any conflicts or overlapping conditions that could cause unintended behavior.

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