πŸ”– 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 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

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, PyRegex or Pythex 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 master when the title does not contain β€œWIP” (ignoring case)
    conditions:
      - base=master
      - -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: