πŸ”– 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 the default repository branch configured on GitHub β€” usually master.

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

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

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.

See example below:

defaults:
  actions:
    comment:
      bot_account: Autobot

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

The config 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 Expression πŸ”—

In 🎯 Conditions you can use regular expression with matching Operators.

Mergify leverages Python regular expression to match rules.

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

Tip

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

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.

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.

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: