Mergify Conditions

Everything you need to know when writing conditions in Mergify


Conditions are an essential component of Mergify rules, as they define the criteria that must be met for a rule to be applied. By utilizing conditions, you can create highly customizable and flexible rules tailored to your specific workflow requirements. Conditions enable you to target pull requests based on various factors such as their status, properties, labels, and associated statuses or checks.

In this guide, we will explore the structure, syntax, and usage of conditions in Mergify rules. You will learn how to craft effective conditions that help you automate and streamline your pull request management process.

A condition in Mergify rules is composed of three key components: attributes, operators, and values, along with optional modifiers. These components work together to define the criteria that must be met for the condition to be considered true.

The grammar for a condition is as follows:

[ "-" ] [ "#" ] <attribute> [ <operator> <value> ]

  • The optional minus (-) operator at the beginning of the condition negates the result of the condition, acting as a “not” operator.

  • The optional hash (#) operator is used to evaluate the length of a list when the attribute is a list.

Attributes represent the properties or characteristics of a pull request that you want to evaluate in your condition. These can include elements such as the number of approvals, the presence of specific labels, or the status of CI checks.

Operators are used to compare the attribute to a specified value. Mergify supports various comparison operators (e.g., =, !=, <, >).

When the attribute is a list, comparison operators behave as if “any” is used on the list, meaning the condition will return true if any element of the list matches the given operator and value.

Values are the reference points used to evaluate the attribute. They can be strings, numbers, or booleans, depending on the attribute being evaluated.

For example, consider the following condition:

#approved-reviews-by>=2

In this condition:

  • The attribute is approved-reviews-by, which represents the list of approved reviewers for a pull request.

  • The operator is >=, which means “greater than or equal to.”

  • The value is 2, which indicates the minimum number of approved reviews required for the condition to be true.

  • The hash (#) operator is used to evaluate the length of the list of approved reviewers.

Understanding the structure of a condition is crucial for creating effective Mergify rules that cater to your specific needs and requirements.

Attributes are properties of pull requests or events used to filter and evaluate the conditions within rules. They can be used to create more specific and targeted rules for your repository.

Pull Request Attributes
Attribute nameValue typeDescription
added-files

list of string

The files that are added by the pull request.

added-lines

list of string

The lines that are added by the pull request.

approved-reviews-by

GitHub login or team

The list of GitHub user or team login that approved the pull request. Team logins are prefixed with the @ character and must belong to the repository organization. This only matches reviewers with admin, write or maintain permission on the repository.

assignee

GitHub login or team

The list of GitHub user or team login that are assigned to the pull request. Team logins are prefixed with the @ character and must belong to the repository organization.

author

GitHub login or team

The GitHub user or team login of the author of the pull request. Team logins are prefixed with the @ character and must belong to the repository organization.

base

branch name

The name of the branch the pull request should be pulled into.

bodystring

The content of the pull request description without Markdown/HTML comments.

body-rawstring

The content of the pull request description.

branch-protection-review-decisionAPPROVED, CHANGES_REQUESTED or REVIEW_REQUIRED

The review decision. This indicates if CODEOWNERS have reviewed the pull request when the Require Review from Code Owners branch protection rule is enabled.

changes-requested-reviews-by

GitHub login or team

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 @ character and must belong to the repository organization. This only matches reviewers with admin, write or maintain permission on the repository.

check-failurestring

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.

check-neutralstring

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.

check-pendingstring

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.

check-skippedstring

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.

check-stalestring

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.

check-successcheck

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.

check-timed-outstring

The list of status checks that timed out 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.

closedboolean

Whether the pull request is closed.

closed-at

Timestamp or relative timestamp

The time the pull request was closed at.

co-authorslist of Commit author

The list of co-authors on the pull request (excluding merge commits and bots).

commented-reviews-by

GitHub login or team

The list of GitHub user or team login that have commented in a review for the pull request. Team logins are prefixed with the @ character and must belong to the repository organization. This only matches reviewers with admin, write or maintain permission on the repository.

commitslist of Commit

The list of commits of the pull request. The index 0 is the first commit of the pull request, while -1 is the last commit of the pull request.

commits-behindstring

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.

commits-unverifiedstring

The list of commit messages that are marked as unverified by GitHub.

conflictboolean

Whether the pull request is conflicting with its base branch.

created-at

Timestamp or relative timestamp

The time the pull request was created at.

current-datetime

Timestamp or timestamp interval

The current date and time.

deleted-lines

list of string

The lines that are deleted by the pull request.

dependabot-dependency-namestring

The dependency-name value included in the Dependabot commit message.

dependabot-dependency-typestring

The dependency-type value included in the Dependabot commit message.

dependabot-update-typestring

The update-type value included in the Dependabot commit message.

dismissed-reviews-by

GitHub login or team

The list of GitHub user or team login that have their review dismissed in the pull request. Team logins are prefixed with the @ character and must belong to the repository organization. This only matches reviewers with admin, write or maintain permission on the repository.

draftboolean

Whether the pull request is in draft state.

files

list of string

The files that are modified, deleted or added by the pull request.

head

branch name

The name of the branch where the pull request changes are implemented.

head-repo-full-namestring

The head branch repository full name (complete version with the organization name).

label

list of string

The list of labels of the pull request.

linear-historyboolean

Whether the pull request commits history is linear (no merge commit).

lockedboolean

Whether the pull request is locked.

mergedboolean

Whether the pull request is merged. This attribute doesn't work on pull requests merged before a rule using this attribute is created.

merged-at

Timestamp or relative timestamp

The time the pull request was merged at.

merged-by

GitHub login or team

The GitHub user or team login that merged the pull request. Team logins are prefixed with the @ character and must belong to the repository organization.

mergify-configuration-changedboolean

Whether the pull request contains changes in the configuration file.

milestonestring

The milestone title associated to the pull request.

modified-files

list of string

The files that are modified by the pull request.

modified-lines

list of string

The lines that are modified by the pull request.

numberstring

The pull request number.

queue-dequeue-reason

Dequeue code for when a pull request has been disembarked from the merge queue.

A dequeue code for when a pull request has been disembarked from the merge queue.

queue-freeze-reasonstring

The reason for the queue containing the pull request to be frozen.

queue-frozenboolean

Whether the pull request is in a queue that is frozen.

queue-merge-started-at

Timestamp or relative timestamp

The time the pull request mergeability checks have started at. NB: This attribute does not work when using Partition Rules.

queue-namestring

The name of the queue containing the pull request.

queue-partition-namestring

The name of the partitions the pull request is queued in.

queue-positionnumber

The position of the pull request in its queue if queued. The first pull request in the queue has position 0. The value is set to -1 if the pull request is not queued. NB: If you are using partitions, this condition returns the maximum position of the pull request from all the partitions it is queued in.

queued-at

Timestamp or relative timestamp

The time the pull request was queued at for merge.

removed-files

list of string

The files that are removed by the pull request.

repository-full-namestring

The current repository full name (complete version with the organization name).

repository-namestring

The current repository name (short version without the organization name).

review-requested

GitHub login or team

The list of GitHub user or team login that were requested to review the pull request. Team logins are prefixed with the @ character and must belong to the repository organization. This only matches reviewers with admin, write or maintain permission on the repository.

review-threads-resolved

list of string

The list of bodies associated to review threads that are marked as resolved by GitHub.

review-threads-unresolved

list of string

The list of bodies associated to review threads that are NOT marked as resolved by GitHub.

schedule

schedule

The current time will be compared against this schedule to un/validate this attribute.

titlestring

The title of the pull request.

updated-at

Timestamp or relative timestamp

The time the pull request was updated at.

Operators allow you to compare attributes with specified values in order to determine if a condition is true or false. Mergify supports several types of operators that cater to different types of comparisons. Familiarizing yourself with these operators is essential for crafting effective conditions in your Mergify rules.

Here is a list of the available operators:

Operator NameSymbolsDescription
Equal

= or :

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

!= or

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

>= or

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 # prefix.
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 # prefix.
Lesser Than or Equal

<= or

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 # prefix.
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 # prefix.

For example, let’s consider a condition that requires a pull request to have a specific label:

label=bugfix

In this condition:

  • The attribute is label, which represents the labels associated with a pull request.

  • The operator is =, which means “equal to.”

  • The value is bugfix, which is the label we want the pull request to have.

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 named work-in-progress.

  • label=enhancement is false because there is no label named enhancement.

  • label!=work-in-progress is false because there is a label named work-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 file README is modified in the pull request.

  • files!=README is true if the file README is not modified in the pull request.

  • files~=^src/ is true if any files in the src directory is modified in the pull request.

  • -files~=^src/ is true if none of the files that are modified are in the src directory.

  • files~=^(README.md|CONTRIBUTING.md)$ is true if the file README.md or CONTRIBUTING.md is modified in the pull requests.

Apply the rule only to pull requests with a specific milestone

Section titled Apply the rule only to pull requests with a specific milestone

In this example, we use the = operator to match a specific milestone for the pull request:

- name: Rule for milestone "v1.0"
conditions:
- milestone="v1.0"
actions:
# Your actions here

Apply the rule only when the number of changes is less than or equal to a certain threshold

Section titled Apply the rule only when the number of changes is less than or equal to a certain threshold

In this example, we use the <= operator to check if the number of files modified in the pull request is less than or equal to 50:

- name: Rule for small changes
conditions:
- "#files<=50"
actions:
# Your actions here

Apply the rule only when the pull request is labeled with at least one of the specified labels

Section titled Apply the rule only when the pull request is labeled with at least one of the specified labels

In this example, we use the != operator to check if the pull request does not have the specified labels:

- name: Rule when not a bug
conditions:
- label!=bug
actions:
# Your actions here

Combining Conditions Using Logical Operators

Section titled Combining Conditions Using Logical Operators

Mergify allows you to combine multiple conditions using logical operators, making it possible to create more intricate rules that cater to your specific workflow requirements. You can use the and and or logical operators to join conditions together.

The and operator is used to join conditions such that all conditions must be true for the overall condition to be true. In Mergify rules, the and operator is represented by placing conditions on separate lines within the same rule.

Alternatively, you can use the and keyword to explicitly group conditions together.

Example:

pull_request_rules:
- name: Merge when all conditions are met
conditions:
- and:
- "#approved-reviews-by>=2"
- "check-success=test job"
actions:
merge:
method: merge

In this example, the pull request will only be merged if it has at least 2 approved reviews and the test job check passes.

The or operator is used to join conditions such that if any one of the conditions is true, the overall condition is considered true. In Mergify rules, the or operator is represented by using the or keyword and specifying conditions as a list.

Example:

pull_request_rules:
- name: Merge when either condition is met
conditions:
- or:
- "#approved-reviews-by>=2"
- "check-success=test job"
actions:
merge:
method: merge

In this example, the pull request will be merged if it has at least 2 approved reviews or if the test job check passes.

Combining conditions using logical operators can help you create more sophisticated rules tailored to your repository’s workflow and requirements.

Testing and Debugging Conditions

Section titled Testing and Debugging Conditions

When crafting conditions for your Mergify rules, it’s essential to test and debug them to ensure they are working as intended. This section will guide you through the process of testing and debugging conditions in your Mergify configuration.

Use the Mergify Configuration Editor

Section titled Use the Mergify Configuration Editor

The Mergify configuration editor is a useful tool to help you test your conditions and rules on existing pull requests without actually triggering the actions defined in your rules. To access the configuration editor, follow these steps:

  1. Navigate to your Mergify dashboard.
  2. Select the repository you want to test.
  3. Click on the “Config Editor” tab.
Mergify Configuration Editor

In the configuration editor, you can enter your conditions and see how they would be evaluated on your pull requests. You can also test your entire Mergify configuration by copying and pasting it into the configuration editor.

Once you have created and committed your Mergify configuration file, Mergify will evaluate the conditions in your rules for each pull request. To debug your conditions and understand why a rule may not be working as expected, you can analyze the Mergify Checks on a pull request:

  1. Navigate to the “Checks” tab of the pull request.
  2. Look for the “Mergify” check in the list of checks.
  3. Click on “Summary” to view the detailed Mergify report.

In the Mergify report, you can see which rules were evaluated and whether the conditions were met or not. This can help you identify any issues in your conditions and make adjustments as necessary.

Mergify Check Summary