๐ 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
anddefaults
.
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 |
---|---|---|
|
string |
The name of the rule. This is not used by the engine directly, but is used when reporting information about a rule. |
|
dictionary with |
This optional key allows to disabled a rule and cancel any ongoing
actions. A reason must be set using the |
|
list of ๐ฏ Conditions |
A list of ๐ฏ Conditions string that must match against the pull request for the rule to be applied. |
|
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 |
---|---|---|
|
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 |
---|---|---|
|
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.
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.