πŸ”– 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 only key is named 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.

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 PyRegex or Pythex to test your regular expression.

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: