🧪 Example Rules🔗
Mergify allows you to define a lot of specific rules and workflows. There is a large number of criterias available to define rules: pull request author, base branch, labels, files, etc.
In this section, we build a few examples that should help you getting started and cover many common use cases.
✅ Automatic Merge when CI works and approving reviews🔗
This is a classic! That rule enables Mergify automatic merge when the continuous integration system validates the pull request and a human reviewed it.
pull_request_rules:
- name: automatic merge for main when CI passes and 2 reviews
conditions:
- "#approved-reviews-by>=2"
- check-success=Travis CI - Pull Request
- base=main
actions:
merge:
method: merge
Of course, you need to adapt the check-success condition to reflect which
CI system you use.
You can tweak this rule as you want. For example, you could use a label such as
work-in-progress to indicate that a pull request is not ready to be merged
— even if's approved:
pull_request_rules:
- name: automatic merge for main when CI passes and 2 reviews and not WIP
conditions:
- "#approved-reviews-by>=2"
- check-success=Travis CI - Pull Request
- base=main
- label!=work-in-progress
actions:
merge:
method: merge
You might want to merge a pull request only if it has been approved by a certain member. You could therefore write such a rule:
pull_request_rules:
- name: automatic merge for main when CI passes approved by octocat
conditions:
- approved-reviews-by=octocat
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge
🗂 Merging based on Modified Files🔗
You could decide to only merge some pull requests based on the files they
touch. You can use the files attribute to access the modified file list and
#files to access the number of files.
This tweak is useful when you want Mergify to merge only data files which can be validated by a script or a linter.
The below sample merges only if data.json changed and if the pull request
passes Circle CI's validation tests:
pull_request_rules:
- name: automatic merge on CircleCI success if only data.json is changed
conditions:
- "check-success=ci/circleci: validate"
- files=data.json
- "#files=1"
actions:
merge:
method: merge
You can also match patterns using regular expression. The following rule merges
the pull requests when the CI passes and when all the files are inside the
src/ directory:
pull_request_rules:
- name: automatic merge on CircleCI success if only data.json is changed
conditions:
- "check-success=ci/circleci: validate"
- -files~=^(!?src/)
actions:
merge:
method: merge
🏖 Less Strict Rules for Stable Branches🔗
Some projects like having easier review requirements for maintenance branches.
That usually means having e.g. 2 review requested for merging into main,
but only one for a stable branch — since those pull request are essentially
backport from main.
To automate the merge in this case, you could write some rules along those:
pull_request_rules:
- name: automatic merge for main when reviewed and CI passes
conditions:
- "check-success=ci/circleci: my_testing_job"
- "#approved-reviews-by>=2"
- base=main
actions:
merge:
method: merge
- name: automatic merge for stable branches
conditions:
- "check-success=ci/circleci: my_testing_job"
- "#approved-reviews-by>=1"
- base~=^stable/
actions:
merge:
method: merge
🎬 Using Labels to Enable/Disable Merge🔗
Some developers are not comfortable with fully automatic merge — they like having a final word before merging the code. In that case, you can add a condition using a label:
pull_request_rules:
- name: automatic merge for main when reviewed and CI passes
conditions:
- check-success=Travis CI - Pull Request
- "#approved-reviews-by>=2"
- base=main
- label=ready-to-merge
actions:
merge:
method: merge
As soon as the pull request has been approved by 2 contributors and gets the
label ready-to-merge, the pull request will be merged by Mergify.
On the other hand, some developers wants an option to disable the automatic
merge feature with a label. This can be useful to indicate that a pull request
labelled as work-in-progress should not be merged:
pull_request_rules:
- name: automatic merge for main when reviewed and CI passes
conditions:
- check-success=continuous-integration/travis-ci/pr
- "#approved-reviews-by>=2"
- base=main
- label!=work-in-progress
actions:
merge:
method: merge
In that case, if a pull request gets labelled with work-in-progress, it
won't be merged, even if approved by 2 contributors and having Travis CI
passing.
⚡️ Using Labels to Prioritize Merge🔗
When using the queue action and many pull requests are waiting to be merged, some of them might be more urgent. In that case, you could add a condition using a label and configure the priority option of the queue action:
pull_request_rules:
- name: automatic merge of 🚑 hotfix (high priority)
conditions:
- check-success=Travis CI - Pull Request
- "#approved-reviews-by>=2"
- base=main
- label=🚑 hotfix
actions:
queue:
method: merge
priority: high
- name: automatic merge of bot 🤖 (low priority)
conditions:
- author=dependabot[bot]
- check-success=Travis CI - Pull Request
- "#approved-reviews-by>=2"
- base=main
actions:
queue:
method: merge
priority: low
- name: automatic merge for main when reviewed and CI passes
conditions:
- check-success=Travis CI - Pull Request
- "#approved-reviews-by>=2"
- base=main
actions:
queue:
method: merge
priority: medium
As soon as the pull request has been approved by 2 contributors, the pull
request will be added to the merge queue. Within the merge queue, the pull
requests with the label 🚑 hotfix will be merged first. The pull requests
from dependabot will always be merged last.
🙅️ Require All Requested Reviews to Be Approved🔗
If all requested reviews have been approved, then the number of
review-requested should become 0. That's not a sufficient condition to
merge though, as you also want to make sure there's at least one positive
review.
pull_request_rules:
- name: merge when all requested reviews are valid
conditions:
- "#approved-reviews-by>=1"
- "#review-requested=0"
- "#changes-requested-reviews-by=0"
actions:
merge:
method: merge
Note that if a requested review is dismissed, then it doesn't count as a review that would prevent the merge.
☑️ Matching Pull Requests with Task Lists🔗
GitHub Markdown allows users to use task lists in their pull request body. Task lists render with clickable checkboxes in comments and you can select or deselect the checkboxes to mark them as complete or incomplete. Tasks lists are often used in pull request templates.
You can leverage Mergify conditions to match task lists using the body
attribute and regular expressions. If your body
contains the following Markdown, you can make sure those boxes are checked
before, e.g., doing a merge.
[ ] Security has been checked
[ ] Changes have been documented
pull_request_rules
- name: merge when checkboxes are checked
conditions:
- body~=(?m)^\[X\] Security has been checked
- body~=(?m)^\[X\] Changes have been documented
- check-success=my favorite ci
actions:
merge:
method: merge
🤖 Bots🔗
Some pull requests might be created automatically by other tools, such as the ones sending automatic dependencies update. You might decide that there's no need to manually review and approve those pull request as long as your continuous integration system validates them.
The rules below are examples for such services: they are designed to
automatically merge those updates without human intervention if the continuous
integration system validates them. Travis CI - Pull Request is used as the
CI check name here — adjust it to whatever you use.
Dependabot🔗
Dependabot is the bot behind GitHub automatic security update. It sends automatic updates for your project's dependencies, making sure they are secure.
You can automate the merge of pull request created by dependabot with a rule such as:
pull_request_rules:
- name: automatic merge for Dependabot pull requests
conditions:
- author=dependabot[bot]
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge
Alternatively, you can also enable the automatic merge for dependabot pull request only if they are for the same major version.
pull_request_rules:
- name: automatic merge for Dependabot pull requests
conditions:
- author=dependabot[bot]
- check-success=Travis CI - Pull Request
- title~=^Bump [^\s]+ from ([\d]+)\..+ to \1\.
actions:
merge:
method: merge
The additional title based rule in conditions make sure that only the
updates from 1.x to 1.y will be automatically merged. Updates from, e.g.,
2.x to 3.x will be ignored by Mergify.
Snyk🔗
Snyk sends automatic updates for your project's dependencies.
pull_request_rules:
- name: automatic merge for Snyk pull requests
conditions:
- title~=^\[Snyk\]
- head~=^snyk-fix
- check-success~=^security/snyk
actions:
merge:
method: merge
Renovate🔗
Renovate sends automatic updates for your project's dependencies.
pull_request_rules:
- name: automatic merge for Renovate pull requests
conditions:
- author=renovate[bot]
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge
Requires.io🔗
Requires.io sends automatic updates for your project's dependencies (only Python's packages).
pull_request_rules:
- name: automatic merge for Requires.io pull requests
conditions:
- title~=^\[requires.io\]
- head~=^requires-io
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge
PyUp🔗
PyUp sends automatic updates for your project's Python dependencies.
pull_request_rules:
- name: automatic merge for PyUp pull requests
conditions:
- author=pyup-bot
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge
Depfu🔗
Depfu notifies you automatically about new versions of your Ruby, JavaScript, and Elixir project's dependencies.
pull_request_rules:
- name: automatic merge for Depfu pull requests
conditions:
- author=depfu[bot]
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge
ImgBot🔗
ImgBot optimizes your images and saves you time.
pull_request_rules:
- name: automatic merge for ImgBot pull requests
conditions:
- author=imgbot[bot]
- check-success=Travis CI - Pull Request
actions:
merge:
method: merge