πŸ§ͺ 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 master when CI passes and 2 reviews
    conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
      - base=master
    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 master when CI passes and 2 reviews and not WIP
    conditions:
      - "#approved-reviews-by>=2"
      - check-success=Travis CI - Pull Request
      - base=master
      - 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 master 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 master, but only one for a stable branch β€” since those pull request are essentially backport from master.

To automate the merge in this case, you could write some rules along those:

pull_request_rules:
  - name: automatic merge for master when reviewed and CI passes
    conditions:
      - "check-success=ci/circleci: my_testing_job"
      - "#approved-reviews-by>=2"
      - base=master
    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 master when reviewed and CI passes
    conditions:
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=master
      - 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-be-merged, 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 master when reviewed and CI passes
    conditions:
      - check-success=continuous-integration/travis-ci/pr
      - "#approved-reviews-by>=2"
      - base=master
      - 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 smart Strict Merge is enabled 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 merge:

pull_request_rules:
  - name: automatic merge of πŸš‘ hotfix (high priority)
    conditions:
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=master
      - label=πŸš‘ hotfix
    actions:
      merge:
        method: merge
        strict: smart
        priority: high
  - name: automatic merge of bot πŸ€– (low priority)
    conditions:
      - author~=^dependabot(|-preview)\[bot\]$
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=master
    actions:
      merge:
        method: merge
        strict: smart
        priority: low
  - name: automatic merge for master when reviewed and CI passes
    conditions:
      - check-success=Travis CI - Pull Request
      - "#approved-reviews-by>=2"
      - base=master
    actions:
      merge:
        method: merge
        strict: smart
        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.

../_images/tasklist.png

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(|-preview)\[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(|-preview)\[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

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