Configuration Data Types

When using templates or conditions, data are made of different types. You will find below the different data types that are available and exposed in Mergify configuration file.

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

You can use a commit object in templates:

{% for commit in commits %}
Co-Authored-By: {{ commit.author }} <{{ commit.email_author }}>
{% endfor %}

You can also use those 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!

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

Mergify leverages 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 contains only days, only times or both and can have a timezone specified with the times (for the list of available time zones, see 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); 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

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

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 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") }}

This describes the reason why a pull request has been removed from the queue.

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.