π 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
master
.
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
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. |
|
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.
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 master when the title does not contain βWIPβ (ignoring case)
conditions:
- base=master
- -title~=(?i)wip
actions:
merge:
method: merge
Template π
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.
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
.
Validation π
Changes to the configuration file should be done via a pull request in order for Mergify to validate it via a GitHub check.
However, if you want to validate your configuration file before sending a pull request, you can use the following command line:
$ curl -F 'data=@.mergify.yml' https://gh.mergify.io/validate
Or by uploading the configuration file with this form: