Configuration Data Types

When using templates or conditions, data comes in different types. The data types available in the Mergify configuration file are listed below.

A commit is an object that embeds information about a Git commit

You can use commit objects in conditions:

pull_request_rules:
  - name: check that commits are not too old
    conditions:
       - commits[*].date_committer < 365 days ago
    actions:
      comment:
        message: One of the commit is too old!

Glob patterns are used by the *= operator in your conditions, by file-pattern scopes, and by barrier_files.

The ** wildcard enables recursive globbing. A few examples:

A brace group matches any one of its comma-separated branches. Mergify expands the group into one pattern per branch, so **/*.{js,ts} is equivalent to listing **/*.js and **/*.ts separately:

pull_request_rules:
  - name: label frontend changes
    conditions:
      - files *= web/**/*.{js,jsx,ts,tsx}
    actions:
      label:
        add:
          - frontend

A pattern can contain several groups, and groups can nest. {a,b{c,d}} matches a, bc and bd, and {src,tests}/**/*.{py,pyi} covers the four combinations of directory and extension.

An unbalanced { or } is a configuration error, not a literal brace. Mergify rejects the configuration instead of leaving you with a pattern that silently matches nothing. To match a brace as a character, escape it as \{ or \}, or bracket it as [{] or [}]; a literal comma inside a group is \,.

A pattern may expand to at most 128 alternatives and nest at most 32 levels deep. Beyond either limit, Mergify rejects the configuration.

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

Mergify uses Python regular expressions to match rules.

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

This format represents a schedule. It can contain only days, only times or both and can have a timezone specified with the times (for the list of available time zones, see the IANA format). If no timezone is specified, it defaults to UTC.

schedule = Mon-Fri
schedule = 09:00-19:00
schedule = 09:00-19:00[America/Vancouver]
schedule != Mon-Fri 09:00-19:00[America/Vancouver]
schedule != SAT-SUN

The timestamp format must follow the ISO 8601 standard. If the timezone is missing, the timestamp is assumed to be in UTC. The supported timezones come from the IANA database.

Supported formats:

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]

- name: end of life version 10.0
  conditions:
    - base = stable/10.0
    - updated-at <= 2021-04-05
  actions:
    comment:
      message: |
        The pull request needs to be rebased after end of life of version 10.0

Mergify supports ISO8601 time intervals for some of the exposed attributes.

If the timezone is missing, the timestamp is assumed to be in UTC. The supported timezones come from the IANA database.

2023-07-13T14:00/2023-07-13T16:00
2023-07-13T14:00:00.123/2023-07-13T16:00:00.123
2023-07-13T14:00Z/2023-07-13T16:00Z
2023-07-13T14:00/2023-07-13T16:00[Europe/Paris]

- name: merge except on new year day
  conditions:
    - current-datetime != 2023-01-01T00:00/2023-01-01T23:59[Europe/Paris]
  actions:
    merge:

Unspecified digits can also be used for some part of the timestamp:

# 14:00 to 19:00 the 14th of July of every year
XXXX-07-14T14:00/XXXX-07-14T19:00[Europe/Paris]

# 14:00 to 19:00 every day of July of every year
XXXX-07-XXT14:00/XXXX-07-XXT19:00[Europe/Paris]

# 14:00 to 19:00 every day of July of 2023
2023-07-XXT14:00/XXXX-07-XXT19:00[Europe/Paris]

# 14:00 to 19:00 every 31st day of every month of 2023
# If a month doesn't have a 31st day it will be skipped
2023-XX-31T14:00/2023-XX-31T19:00[Europe/Paris]

# 14:00 to 19:00 every 31st day of every month of every year
XXXX-XX-31T14:00/XXXX-XX-31T19:00[Europe/Paris]

Timestamps can be expressed relative to the current date and time. The format is [DD days] [HH hours] [MM minutes] 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 is translated to updated-at >= 2020-06-04T00:00:00.

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

Duration can be expressed as quantity unit [quantity unit...] where quantity is a number (possibly signed) and unit is second, minute, hour, or day (abbreviations and plurals are accepted).

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

Priority values can be expressed by using an integer between 1 and 10000. You can also use those aliases:

• low (1000)
• medium (2000)
• high (3000)

priority_rules:
  - name: my hotfix priority rule
    conditions:
      - base = main
      - label = hotfix
      - check-success = linters
    priority: high

  - name: my low priority rule
    conditions:
      - base = main
      - label = low
      - check-success = linters
    priority: 550

Some fields are rendered as templates before Mergify uses them. Most accept variable substitution (short {{ name }} placeholders filled with pull request data); a few still use the legacy Jinja2 language.

Several fields let you insert pull request data using variables:

Thank you {{ author }} for your contribution!

renders to:

Thank you jd for your contribution!

when the pull request author login is jd.

A variable is written as {{ name }} (surrounding spaces are optional). Every other character is kept as-is. Each templated field accepts a specific set of variables, documented as its data type below.

Used by the comment, review and close message fields.

The {{ assignees }} and {{ approvers }} variables render as ready-to-use @-mentions for the pull request’s assignees and the people who approved it. For example, the template:

Thanks {{ approvers }} for the review!

renders to:

Thanks @alice, @bob for the review!

when the pull request was approved by alice and bob.

Used by the copy and backport title field.

Used by the copy and backport body field.

Used by the github_actions workflow input values.

A GitHub login. You can also use the {{ author }} variable to target the pull request author. Used by the assign users, add_users and remove_users fields.

A GitHub login. You can also use {{ author }} (the pull request author) and {{ merged_by }} (the user who merged the original pull request). Used by the copy and backport assignees field.

A GitHub login Mergify impersonates to perform an action. You can also use the {{ author }} variable to act as the pull request author. Used by the bot_account field of the comment, edit, copy, merge, rebase, request_reviews, review, squash and update actions, and the merge queue draft_bot_account, merge_bot_account and update_bot_account.

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 let you use any of the pull request attributes 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 }}

Mergify also provides custom Jinja2 filters:

• markdownify: to convert HTML to Markdown:

{{ body | markdownify }}

• get_section(<section>, <default>): to extract one Markdown section

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

Either none, read, triage, write, maintain or admin.

This describes the reason why a pull request’s merge queue checks ended: either because the pull request left the queue, or because its checks were interrupted while it stayed in the queue.

The following reasons can be reported:

Report modes allow you to choose the type of report you want for your actions. Report mode values can be expressed in the configuration as a list of strings. The default value is ["check"] and the list can’t be empty. To fill the list, the following report modes are available:

Report mode option is currently supported for only the following actions: backport, copy.