πŸ”– Configuration FileπŸ”—

File UsedπŸ”—

Mergify uses the configuration file that is:

  • The file named .mergify.yml, or, as a fallback, .mergify/config.yml or .github/mergify.yml from the root directory.

  • In the default repository branch configured on GitHub β€” usually main.

FormatπŸ”—

Here’s what you need to know about the file format:

  • The file format is YAML.

  • The file main type is a dictionary whose keys are named pull_request_rules and defaults.

Pull Request RulesπŸ”—

  • The value type of the pull_request_rules is list.

  • Each entry in pull_request_rules must be a dictionary.

Each dictionary must have the following keys:

Key Name

Value Type

Value Description

name

string

The name of the rule. This is not used by the engine directly, but is used when reporting information about a rule.

conditions

list of 🎯 Conditions

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

actions

dictionary of πŸš€ Actions

A dictionary made of πŸš€ Actions that will be executed on the matching pull requests.

The rules are evaluated in the order they are defined in pull_request_rules and, therefore, the actions are executed in that same order.

See πŸ§ͺ Example Rules for configuration file examples.

Queue RulesπŸ”—

  • The value type of the queue_rules is list.

  • Each entry in queue_rules must be a dictionary.

See Queue Rules for the complete list and description of options.

DefaultsπŸ”—

  • The value type of defaults is a dictionary.

This dictionary must have the following key:

Key Name

Value Type

Value Description

actions

dictionary of πŸš€ Actions

A dictionary made of πŸš€ Actions whose configuration will be used by default.

The defaults section is used to define default configuration valued for actions run by pull request rules and by βš™οΈ Commands. If the options are defined in pull_request_rules they are used, otherwise, the values set in defaults are used.

For example:

defaults:
  actions:
    comment:
      bot_account: Autobot

pull_request_rules:
  - name: comment with default
    conditions:
      - label=comment
    actions:
      comment:
        message: I πŸ’™ Mergify

The configuration above is the same as below:

pull_request_rules:
  - name: comment with default
    conditions:
      - label=comment
    actions:
      comment:
        message: I πŸ’™ Mergify
        bot_account: Autobot

Data TypesπŸ”—

Regular ExpressionsπŸ”—

Tip

You can use regex101 or PyRegex to test your regular expressions.

You can use regular expression with matching operators in your conditions .

Mergify leverages Python regular expressions to match rules.

ExamplesπŸ”—

pull_request_rules:
  - name: add python label if a Python file is modified
    conditions:
      - files~=\.py$
    actions:
      label:
        add:
          - python

  - name: automatic merge for main when the title does not contain β€œWIP” (ignoring case)
    conditions:
      - base=main
      - -title~=(?i)wip
    actions:
      merge:
        method: merge

TemplateπŸ”—

Note

You need to replace the - character by _ from the pull request attribute names when using templates. The - is not a valid character for variable names in Jinja2 template.

The template data type is a regular string that is rendered using the Jinja2 template language.

If you don’t need any of the power coming with this templating language, you can just use this as a regular string.

However, those templates allow to use any of the pull request attribute in the final string.

For example the template string:

Thank you @{{author}} for your contribution!

will render to:

Thank you @jd for your contribution!

when used in your configuration file β€” considering the pull request author login is jd.

ValidationπŸ”—

Changes to the configuration file should be done via a pull request in order for Mergify to validate it via a GitHub check.

However, if you want to validate your configuration file before sending a pull request, you can use the following command line:

$ curl -F 'data=@.mergify.yml' https://gh.mergify.io/validate

Or by uploading the configuration file with this form: