๐Ÿ”– 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, queue_rules, commands_restrictions 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.

disabled

dictionary with reason key

This optional key allows to disabled a rule and cancel any ongoing actions. A reason must be set using the reason key.

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.

Commands Restrictions๐Ÿ”—

  • The value type of the commands_restrictions is dictionary.

  • Each entry in commands_restrictions must be an ๐Ÿš€ Actions name and a dictionary.

Each dictionary must have the following keys:

Key Name

Value Type

Value Description

conditions

list of ๐ŸŽฏ Conditions

A list of ๐ŸŽฏ Conditions string that must match against the pull request for the command to be allowed.

For example, to limit backport commands for pull requests coming from the main branch:

commands_restrictions:
  backport:
    conditions:
    - base=main

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๐Ÿ”—

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

Mergify leverages Python regular expressions to match rules.

Tip

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

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

Time๐Ÿ”—

This format represents the time of the day in the 24-hours format. It can be used with any of the greater and lesser operators (>=, >, <=, <).

current-time>=18:00[Europe/Paris
schedule: Mon-Fri 09:00-19:00[America/Vancouver]
schedule: Mon-Fri 09:00[Europe/Paris]-19:00[America/Vancouver]

Examples๐Ÿ”—

- name: comment after 18:00
  conditions:
    - current-time>=18:00
  actions:
    close:
      message: It's too late for this!
- name: merge on working hour
  conditions:
    - schedule: Mon-Fri 09:00-19:00[America/Vancouver]
  actions:
    merge:

Timestamp๐Ÿ”—

The timestamp format must follow the ISO 8601 standard. If the timezone is missing, the timestamp is assumed to be in UTC.

2021-04-05
2012-09-17T22:02:51
2008-09-22T14:01:54Z
2013-12-05T07:19:04-08:00
2013-12-05T07:19:04[Europe/Paris]

Examples๐Ÿ”—

- name: end of life version 10.0
  conditions:
    - base=stable/10.0
    - -closed
    - current-timestamp>=2021-04-05
  actions:
    close:
      message: |
        The pull request base branch has reached end-of-life.

Relative Timestamp๐Ÿ”—

Timestamps can be expressed relative to the current date and time. The format is [DD days] [HH:MM] ago:

  • DD, the number of days

  • HH, the number of hours

  • MM, the number of minutes

If the current date is 18th June 2020, updated-at>=14 days ago will be translated updated-at>=2020-06-04T00:00:00.

Examples๐Ÿ”—

- name: close stale pull request
  conditions:
    - base=main
    - -closed
    - updated-at<14 days ago
  actions:
    close:
      message: |
        This pull request looks stale. Feel free to reopen it if you think it's a mistake.

Duration๐Ÿ”—

Duration can be expressed as quantity unit [quantity unit...] where quantity is a number (possibly signed); unit is second, minute, hour, day, week, or abbreviations or plurals of these units;

1 day 15 hours 6 minutes 42 seconds
1 d 15 h 6 m 42 s

YAML Anchors and Aliases๐Ÿ”—

The configuration file supports YAML anchors and aliases <https://yaml.org/spec/1.2.2/#anchors-and-aliases>. It allows reusing configuration sections. For example, you could reuse the list of continuous integration checks:

queue_rules:
  - name: hotfix
    conditions:
      - and: &CheckRuns
        - check-success=linters
        - check-success=unit
        - check-success=functionnal
        - check-success=e2e
        - check-success=docker

  - name: default
    conditions:
      - and: *CheckRuns
      - schedule=Mon-Fri 09:00-17:30[Europe/Paris]

pull_request_rules:
  - name: automatic merge for hotfix
    conditions:
      - label=hotfix
      - and: *CheckRuns
    actions:
      queue:
        name: hotfix

  - name: automatic merge reviewed pull request
    conditions:
      - "#approved-reviews-by>=1"
      - and: *CheckRuns
    actions:
      queue:
        name: default

Disabling Rules๐Ÿ”—

You can disable a rule while keeping it in the configuration. This allows gracefully handling the cancellation of any ongoing actions (e.g., like stopping the merge queue).

Examples๐Ÿ”—

- name: automatic merge for main when the title does not contain โ€œWIPโ€ (ignoring case)
  disabled:
    reason: code freeze
  conditions:
    - base=main
    - -title~=(?i)wip
  actions:
    merge:
      method: merge

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.

Jinja2 filters are supported, you can build string from list for example with:

Approved by: @{{ approved_reviews_by | join(', @') }}

Jinja2 string manipulation are also supported, you can split string for example with:

{{ body.split('----------')[0] | trim }}

We also provide custom Jinja2 filters:

  • markdownify: to convert HTML to Markdown:

{{ body | markdownify }}
  • get_section(<section>, <default>): to extract one Markdown section

{{ body | get_section("## Description") }}

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.

Note

By default, the HTML comments are stripped from body. To get the full body, you can use the body_raw attribute.