Configuration Data Types

The different data types you can find in Mergify configuration file

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.

Commit

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

Key name	Value type
`sha`	`string`
Commit sha
`parents`	list of string
List of parents sha
`commit_message`	`string`
The commit message
`commit_verification_verified`	`boolean`
Whether the commit was verified by GitHub
`author`	`string`
The commit author
`date_author`	Timestamp
The date the commit was authored
`email_author`	`string`
The email address of the commit author
`committer`	`string`
The committer
`date_committer`	Timestamp
The date the commit was committed

You can use a commit object in templates:

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

You can also use those objects in conditions:

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

Commit Author

Key name	Value type
`name`	`string`
Author name
`email`	`string`
Author email address

Regular Expressions

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

Mergify leverages Python regular expressions to match rules.

Note

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

1
pull_request_rules:
2
  - name: add python label if a Python file is modified
3
    conditions:
4
      - files~=\.py$
5
    actions:
6
      label:
7
        add:
8
          - python
9

10
  - name: automatic merge for main when the title does not contain “WIP” (ignoring case)
11
    conditions:
12
      - base=main
13
      - -title~=(?i)wip
14
    actions:
15
      merge:
16
        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.

Warning

Schedule can be only used with the equality operators = and !=.

1
schedule = Mon-Fri
2
schedule = 09:00-19:00
3
schedule = 09:00-19:00[America/Vancouver]
4
schedule != Mon-Fri 09:00-19:00[America/Vancouver]
5
schedule != SAT-SUN

Timestamp

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:

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

1
- name: end of life version 10.0
2
  conditions:
3
    - base=stable/10.0
4
    - updated-at<=2021-04-05
5
  actions:
6
    comment:
7
      message: |
8
        The pull request needs to be rebased after end of life of version 10.0

Timestamp Interval

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.

1
2023-07-13T14:00/2023-07-13T16:00
2
2023-07-13T14:00:00.123/2023-07-13T16:00:00.123
3
2023-07-13T14:00Z/2023-07-13T16:00Z
4
2023-07-13T14:00/2023-07-13T16:00[Europe/Paris]

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

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

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

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

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

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

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

Relative Timestamp

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

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.

1
- name: close stale pull request
2
  conditions:
3
    - base=main
4
    - -closed
5
    - updated-at<14 days ago
6
  actions:
7
    close:
8
      message: |
9
        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
1 day 15 hours 6 minutes 42 seconds
2
1 d 15 h 6 m 42 s

Priority

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)

1
priority_rules:
2
  - name: my hotfix priority rule
3
    conditions:
4
      - base=main
5
      - label=hotfix
6
      - check-success=linters
7
    priority: high
8

9
  - name: my low priority rule
10
    conditions:
11
      - base=main
12
      - label=low
13
      - check-success=linters
14
    priority: 550

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 attributes in the final string.

For example the template string:

1
Thank you @{{author}} for your contribution!

will render to:

1
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:

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

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

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

Mergify also provides custom Jinja2 filters:

markdownify: to convert HTML to Markdown:

1
{{ body | markdownify }}

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

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

Warning

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.

Queue Dequeue Reason

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

Reason	Description
`pr-merged`	Pull request has been merged.
`pr-dequeued`	Pull request has been removed from the queue by an dequeue command or by an automation rule
`checks-timeout`	The configured `checks_timeout` has been reached.
`checks-failed`	The checks have failed.
`queue-rule-missing`	The queue rule has been removed from the configuration.
`target-branch-missing`	The pull request base branch is missing.
`target-branch-changed`	The pull request base branch has changed.
`pr-unexpectedly-failed-to-merge`	An unexpected error happened while merging the pull request.
`batch-max-failure-resolution-attempts`	The maximum number of resolution attempts set in `batch_max_failure_resolution_attempts` has been reached.
`conflict-with-base-branch`	The pull request conflicts with its base branch.
`conflict-with-pull-ahead`	The pull request conflicts with a pull request ahead of it.
`branch-update-failed`	Updating the head branch of the pull request failed.

Edit on GitHub