๐ฏ Conditions๐
Conditions are used in pull request rules and queue rules to check if a pull
request matches a certain rule. If a pull request matches all of the listed
conditions in a rule, the subsequent actions listed in that rule will be
applied. Conditions must be listed under the conditions
section of the
pull_request_rules
or queue_rules
entries โ see ๐ Configuration File.
Grammar๐
A condition is a string that has the following format:
[ "-" ] [ "#" ] <attribute> [ <operator> <value> ]
The optional
-
prefix is equivalent to the not operator.The optional
#
prefix indicates to consider the length of the attribute value rather than its content.An
attribute
is a property of a pull request, such as its author, its title or its base branch.An
operator
is used to determine how the match between the pull request'sattribute
and the definedvalue
occurs.
For example:
author=jd
evaluates to true if the GitHub login of the author of the pull request isjd
.base~=^stable/
matches any pull request whose base branch matches the regular expression^stable/
.approved-reviews-by=sileht
matches if the usersileht
is in the list of contributors who approved the pull request.#approved-reviews-by>=2
matches if at least 2 collaborators approved the pull request.-merged
matches if the pull requested has not been merged.
Important
The #
character is considered as a comment delimiter in YAML. As #
is the length operator in Mergify's conditions system, don't forget to use
"
around the condition to write valid YAML syntax.
Note
operator
and value
are only optional if the attribute
type is
Boolean
.
Combining Conditions with Operators๐
The conditions do support the or
and and
operators.
For example, you can match if its author is foo
or
bar
, you could write:
conditions:
- or:
- author=foo
- author=bar
You can also combine or
and and
like this:
conditions:
- or:
- and:
- author=foo
- label=core
- and:
- author=bar
- label=backend
Note
The depth on combined conditions is limited to 4.
Attributes๐
Here's the list of pull request attribute that can be used in conditions:
Attribute Name |
Value type |
Value description |
---|---|---|
|
list of string |
The list of GitHub user or team login that are assigned to the pull request.
Team logins are prefixed with the |
|
list of string |
The list of GitHub user or team login that approved the pull request.
Team logins are prefixed with the |
|
string |
The GitHub user or team login of the author of the pull request.
Team logins are prefixed with the |
|
string |
The name of the branch the pull request should be pulled into. |
|
string |
The contents of the pull request description without Markdown/HTML comments. |
|
string |
The contents of the pull request description. |
|
list of string |
The list of GitHub user or team login that have requested changes in a
review for the pull request.
Team logins are prefixed with the |
|
Boolean |
Whether the pull request is closed. |
|
Boolean |
Whether the pull request is conflicting with its base branch. |
|
list of string |
The list of GitHub user or team login that have commented in a review
for the pull request.
Team logins are prefixed with the |
|
list of string |
The list of GitHub user or team login that have their review dismissed
in the pull request.
Team logins are prefixed with the |
|
Boolean |
Whether the pull request is in draft state. |
|
list of string |
The files that are modified, deleted or added by the pull request. |
|
string |
The name of the branch where the pull request changes are implemented. |
|
list of string |
The list of labels of the pull request. |
|
Boolean |
Whether the pull request commits history is linear (no merge commit). |
|
Boolean |
Whether the pull request is locked. |
|
Boolean |
Whether the pull request is merged. |
|
string |
The GitHub user or team login that merged the pull request.
Team logins are prefixed with the |
|
string |
The milestone title associated to the pull request. |
|
integer |
The pull request number. |
|
list of string |
The list of commit messages of the pull request. |
|
integer |
The position of the pull request in its queue if queued. The first pull
request in the queue has position |
|
The time the pull request was queued at for merge. |
|
|
The time the pull request mergeability checks have started at. |
|
|
list of commits |
The list of commits between the head of the base branch and the base of the pull request. This can only be used with the length operator as #commits-behind. |
|
list of string |
The list of GitHub user or team login that were requested to review the
pull request.
Team logins are prefixed with the |
|
list of string |
The list of status checks that successfully passed for the pull request. This is the name of a status check such as continuous-integration/travis-ci/pr or of a check run such as Travis CI - Pull Request. See About Status Checks for more details. |
|
list of string |
The list of status checks that are neutral for the pull request. This is the name of a status check such as continuous-integration/travis-ci/pr or of a check run such as Travis CI - Pull Request. See About Status Checks for more details. |
|
list of string |
The list of status checks that failed for the pull request. This is the name of a status check such as continuous-integration/travis-ci/pr or of a check run such as Travis CI - Pull Request. See About Status Checks for more details. Checks that report being cancelled, timed out, and action required are also considered as failures. |
|
list of string |
The list of status checks that was skipped for the pull request. This is the name of a status check such as continuous-integration/travis-ci/pr or of a check run such as Travis CI - Pull Request. See About Status Checks for more details. |
|
list of string |
The list of status checks that is pending for the pull request. This is the name of a status check such as continuous-integration/travis-ci/pr or of a check run such as Travis CI - Pull Request. See About Status Checks for more details. |
|
list of string |
The list of status checks that are stale for the pull request. This is the name of a status check such as continuous-integration/travis-ci/pr or of a check run such as Travis CI - Pull Request. See About Status Checks for more details. |
|
string |
The title of the pull request. |
|
The time the pull request was created at. |
|
|
The time the pull request was updated at. |
|
|
The time the pull request was merged at. |
|
|
The time the pull request was closed at. |
|
|
The current date and time. |
|
|
The current time in format |
|
|
integer |
The current day of the month, from 1 to 31. |
|
integer |
The current month, from 1 to 12. |
|
integer |
The current year, from 1900 to 9999. |
|
integer or string |
The current day of the week. From 1 (Monday) to 7 (Sunday), or one of
|
|
string |
A schedule, e.g., |
|
list of strings |
The list of commit messages that are marked as |
|
list of strings |
The list of bodies associated to review threads that are marked as |
|
list of strings |
The list of bodies associated to review threads that are NOT marked as |
|
string |
The current repository name (short version without the organization name). |
|
string |
The current repository full name (complete version with the organization name). |
Warning
Time-based conditions have a 5 minutes precision at best. Do not write conditions based on time ranges that are too narrow or the condition might never be true.
Note
current-timestamp
, current-time
, created-at
, updated-at
,
closed-at
and merged-at
do not support the ~=
, =
and !=
operators. schedule
only supports the =
and !=
operators.
Note
The timezone for all time-based conditions is UTC.
Operators๐
Operator Name |
Symbol |
Operator Description |
---|---|---|
Equal |
|
This operator checks for strict equality. If the target attribute type is a list, each element of the list is compared against the value and the condition is true if any value matches. |
Not Equal |
|
This operator checks for non equality. If the target attribute type is a list, each element of the list is compared against the value and the condition is true if no value matches. |
Match |
|
This operator checks for regular expressions matching. If the target attribute type is a list, each element of the list is matched against the value and the condition is true if any value matches. |
Greater Than or Equal |
|
This operator checks for the value to be greater than or equal to the
provided value. It's usually used to compare against the length of a
list using the |
Greater Than |
|
This operator checks for the value to be greater than the provided
value. It's usually used to compare against the length of a list using
the |
Lesser Than or Equal |
|
This operator checks for the value to be lesser then or equal to the
provided value. It's usually used to compare against the length of a
list using the |
Lesser Than |
|
This operator checks for the value to be lesser than the provided value.
It's usually used to compare against the length of a list using the
|
How To Match Lists๐
Some attributes have a type of list
. Most Operators are able to match
value against lists: they will iterate over all the values of the list and
return true if any of the value matches.
For example, the label
attribute is a list of string containing the names
of the label attached to a pull request. With a pull request whose labels are
(bug, work-in-progress)
, then:
label=work-in-progress
is true because there is a label namedwork-in-progress
.label=enhancement
is false because there is no label namedenhancement
.label!=work-in-progress
is false because there is a label namedwork-in-progress
.label~=^work
is true because there is a label matching the regular expression^work
.-label~=^work
is false because there is a label matching the regular expression^work
but the condition is reversed with the-
prefix.
The same applies for the files
attribute โ which contains the list of
modified files:
files=README
is true if the fileREADME
is modified in the pull request.files!=README
is true if the fileREADME
is not modified in the pull request.files~=^src/
is true if any files in thesrc
directory is modified in the pull request.-files~=^src/
is true if none of the files that are modified are in thesrc
directory.
About Status Checks๐
Generic Status Check๐
When using the check-success
, check-neutral
, check-failure
,
check-skipped
, check-pending
, and check-stale
conditions, you need to use the name of your check service. This can be find by
opening an existing pull request and scrolling down near the Merge
button.

The name of the status check is written in bold on the left side. In the
example above, it should be Uno.UI - CI
. A condition that would make sure
this checks succeed before doing any action should be written as:
conditions:
- check-success=Uno.UI - CI
GitHub Actions๐
GitHub Actions works slightly differently. To match a status check when using GitHub Action, only the job name is used.

In the example above, it would be A job to say hello
:
conditions:
- check-success=A job to say hello
Validating All Status Checks๐
A common condition is to require that "every status check (CI) passes" โ especially before executing the merge action.
There is no such thing as "every status check" in GitHub.
Here's why:
Each pull request can have its own custom list of status checks.
On creation, or when a new commit is pushed, a pull request has no status check.
A status check might not be reported by a service (CI) (e.g., because it's broken) and therefore be absent.
Those three facts make it mandatory to write explicitly the checks that are expected for your condition to be valid. Therefore you must list explicitly every status check that is expected, e.g.:
conditions:
- check-success=build: Windows
- check-success=build: Linux
Do not use conditions such as:
#check-failure=0
, because this will be true as soon as the pull request is created and before any service report its status (see point 2. above).check-success~=build
while expecting this to wait for "all" status checks that havebuild
in their name (see point 1. and 2.above).
Such conditions won't do what you want them to do.
About Branch Protection๐
GitHub allows you to enable branch protection settings on your repository. For some of the branch protection parameters, listed below, Mergify is going to generate corresponding conditions in pull request and queue rules:
Require a pull request before merging
withRequire approvals
Require status checks to pass before merging
Require conversation resolution before merging
Thus, enabling Require a pull request before merging
and
Require approvals
will set the following condition:
conditions:
- "#approved-reviews-by>=1"
- "#changes-requested-reviews-by=0"
Enabling Require status checks to pass before merging
will set the
following condition for each checks in your repository:
conditions:
- and:
- or:
- check-success=continuous-integration/travis-ci
- check-neutral=continuous-integration/travis-ci
- check-skipped=continuous-integration/travis-ci
- or:
- check-success=continuous-integration/circle-ci
- check-neutral=continuous-integration/circle-ci
- check-skipped=continuous-integration/circle-ci
...
Enabling Require conversation resolution before merging
will set the
following condition:
conditions:
- "#review-threads-unresolved=0"
Each condition generated by the branch protection settings will be tagged with a description note in order to notify its provenance.
