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:

• pull_request_rules configures Automation Workflow;

• merge_protections configures Merge Protections;

• queue_rules configures the Merge Queue;

• merge_queue configures option common to all the queues of the [Merge Queue])(/merge-queue);

• priority_rules configures the priorities for the Merge Queue;

• partition_rules configures monorepository support in 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.

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:

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

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

null

true

false

true

null

30 seconds

1

queue

null

null

null

null

null

null

mergify/merge-queue/

1

null

null

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.

true

medium

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.

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
    allow_inplace_checks: False

  - name: default with smaller batch
    allow_inplace_checks: False
    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
    allow_inplace_checks: False
    batch_size: 10

  - name: default with smaller batch
    allow_inplace_checks: False
    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.

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

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.

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.