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.

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

Key nameValue type

Commit sha


list of string

List of parents sha


The commit message


Whether the commit was verified by GitHub


The commit author



The date the commit was authored


The email address of the commit author


The committer



The date the commit was committed

You can use a commit object in templates:

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

You can also use those objects in conditions:

  - name: check that commits are not too old
       - commits[*].date_committer < 365 days ago
        message: One of the commit is too old!
Key nameValue type

Author name


Author email address

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

Mergify leverages Python regular expressions to match rules.

  - name: add python label if a Python file is modified
      - files~=\.py$
          - python

  - name: automatic merge for main when the title does not contain “WIP” (ignoring case)
      - base=main
      - -title~=(?i)wip
        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:

- name: end of life version 10.0
    - base=stable/10.0
    - updated-at<=2021-04-05
      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.

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

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

# 14:00 to 19:00 the 14th of July of every year

# 14:00 to 19:00 every day of July of every year

# 14:00 to 19:00 every day of July of 2023

# 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

# 14:00 to 19:00 every 31st day of every month of every year

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
    - base=main
    - -closed
    - updated-at < 14 days 3 hours 2 minutes ago
      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)
  - name: my hotfix priority rule
      - base=main
      - label=hotfix
      - check-success=linters
    priority: high

  - name: my low priority rule
      - 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.

nonePull request was not and is not in any queue.
pr-mergedPull request has been merged.

Pull request has been removed from the queue by an dequeue command or by an automation rule


The configured checks_timeout has been reached.

checks-failedThe checks have failed.
queue-rule-missingThe queue rule has been removed from the configuration.
base-branch-missingThe pull request base branch is missing.
base-branch-changedThe pull request base branch has changed.
pr-unexpectedly-failed-to-mergeAn unexpected error happened while merging the pull request.
batch-max-failure-resolution-attemptsThe maximum number of resolution attempts set in batch_max_failure_resolution_attempts has been reached.
conflict-with-base-branchThe pull request conflicts with its base branch.
conflict-with-pull-aheadThe pull request conflicts with a pull request ahead of it.
branch-update-failedUpdating the head branch of the pull request failed.
pr-ahead-dequeuedA pull request which is ahead has been removed from the queue.
pr-ahead-failed-to-mergeThe pull request which is ahead could not be merged.
pr-with-higher-priority-queuedA higher priority pull request has been queued in the meantime.
pr-queued-twiceThe pull request got queued twice.
pr-frozen-no-cascadingThe pull request was frozen by a freeze with cascading effect disabled.
pr-checks-stopped-because-merge-queue-pauseThe checks have been interrupted because the merge queue is paused on this repository.
draft-pull-request-changedThe draft pull request has been unexpectedly changed.
pull-request-updatedThe pull request has been manually updated.
merge-queue-resetThe merge queue was reset.
incompatibility-with-branch-protectionsThe pull request cannot be checked because of an incompatibility with branch protections.

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:

checkReport the action’s result as a GitHub check on the Pull Request. This is the default report mode.
commentReport the action’s result as a comment on the Pull Request

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