๐ 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
.The configuration can be extended once by another configuration using the keyword
extends
.
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
,partition_rules
,commands_restrictions
,defaults
,shared
andextends
.
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 |
---|---|---|
|
dictionary of ๐ Actions |
A dictionary made of ๐ Actions that will be executed on the matching pull requests. |
|
list of ๐ฏ Conditions |
A list of ๐ฏ Conditions string that must match against the pull request for the rule to be applied. |
|
dictionary with |
This optional key allows to disabled a rule and cancel any ongoing
actions. A reason must be set using the |
|
string |
The name of the rule. This is not used by the engine directly, but is used when reporting information about a rule. It's not possible to have two rules with the same name. |
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.
Partition Rules๐
The value type of the
partition_rules
is a list.Each entry in
partition_rules
must be a dictionary.
See Partition 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
Another example, to limit backport commands usage to a specific team (or user):
commands_restrictions:
backport:
conditions:
- [email protected]
Or to limit backport commands for users with a specific permission on the repository.
commands_restrictions:
backport:
conditions:
- sender-permission>=write
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๐
Commits๐
List of commit object.
Example structure of a commit object:
{
"sha": "foo-sha",
"parents": ["parent-foo-sha", "another-parent-foo-sha"],
"commit_message": "a commit message",
"commit_verification_verified": True,
"author": "commit-author",
"date_author": "2012-04-14T16:00:49Z",
"email_author": "[email protected]",
"committer": "commit-committer",
"date_committer": "2012-04-15T16:00:49Z"
"email_committer": "[email protected]",
}
Using the list of commit within a template:
{% for commit in commits %}
Co-Authored-By: {{ commit.author }} <{{ commit.email_author }}>
{% endfor %}
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
Schedule๐
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 will default to UTC.
It can be used with the equality operators =
and !=
.
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
Examples๐
- 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
- updated-at<=2021-04-05
actions:
comment:
message: |
The pull request needs to be rebased after end of life of version 10.0
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
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)
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
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.
YAML Anchors and Aliases๐
The configuration file supports YAML anchors and aliases. It allows reusing configuration sections. For example, you could reuse the list of continuous integration checks:
queue_rules:
- name: hotfix
merge_conditions:
- and: &CheckRuns
- check-success=linters
- check-success=unit
- check-success=functionnal
- check-success=e2e
- check-success=docker
- name: default
merge_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).
Example๐
- 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
Extends๐
extends
is an optional key with its value type being a string.
You can extend a configuration once by inheriting the configuration from another
repository configuration where Mergify is installed. The value of the
extends
key is a repository name.
extends: my_repo
The local configuration inherits rules from the remote configuration. Remote rules will be overridden by the local configuration if they have the same name.
Example:
remote_repository/.mergify.yml
pull_request_rules:
- name: comment with default
conditions:
- label=comment
actions:
comment:
message: I am a default comment ๐
- name: comment when closed
conditions:
- label=closed
actions:
comment:
message: Closed by Mergify ๐
commands_restrictions:
backport:
conditions:
- base=main
.mergify.yml
extends: remote_repository
pull_request_rules:
- name: comment with default
conditions:
- label=comment
actions:
comment:
message: I ๐ Mergify
commands_restrictions:
backport:
conditions:
- [email protected]
The result will be:
pull_request_rules:
- name: comment with default
conditions:
- label=comment
actions:
comment:
message: I ๐ Mergify
- name: comment when closed
conditions:
- label=closed
actions:
comment:
message: Closed by Mergify ๐
commands_restrictions:
backport:
conditions:
- [email protected]
Warning
Values in the shared
key will not be merged and shared between local and
remote configurations.
Note
Values in the default
key will be merged and remote default values will
apply to local configuration.
OpenAPI specification๐
The configuration file format is available as a OpenAPI schema.