πŸ§ͺ Example Rules πŸ”—

Mergify allows you to define a lot of specific rules. 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

You can tweak as fine as you want. For example, many users like to 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

If you are already using the GitHub Branch Protection system. You can just use:

pull_request_rules:
  - name: automatic merge when GitHub branch protection passes on master
    conditions:
      - base=master
    actions:
      merge:
        method: merge

You can also remove the branch limitation so it’d work on any branch:

pull_request_rules:
  - name: automatic merge when GitHub branch protection passes
    conditions: []
    actions:
      merge:
        method: merge

πŸŒ€ Using Regular Expressions πŸ”—

You can use regular expressions in the πŸ”– Configuration File, associated with flags to enhance it. To match a pull request title which contains the β€œWIP” statement, ignoring the case, you can write:

pull_request_rules:
  - name: automatic merge for master when the title contains β€œWIP” (ignoring case)
    conditions:
      - base=master
      - title~=(?i)wip
    actions:
      merge:
        method: merge

You can also use regular expressions to match filenames. For example, to merge your pull request if at least one Python file is modified and if it passes Circle CI’s validation tests:

pull_request_rules:
  - name: automatic merge for master when CI passes and if at least one Python file is modified
    conditions:
      - "check-success=ci/circleci: validate"
      - files~=\.py$
    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 the script, linter, etc.

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

πŸ‘©β€πŸ”§ Using Labels to Backport Pull-Requests πŸ”—

Copying pull requests to a maintenance branch is something common as explained in backport. In order to elect a pull request to be backported, it’s common to use a label. You could write a rule such as:

pull_request_rules:
  - name: backport patches to stable branch
    conditions:
      - base=master
      - label=backport-to-stable
    actions:
      backport:
        branches:
          - stable

You could also manually trigger them using the backport command.

βœ‚οΈ Deleting Merged Branch πŸ”—

Some users create pull request from the same repository by using different branches β€” rather than creating a pull request from a fork. That’s fine, but it tends to leave a lot of useless branch behind when the pull request is merged.

Mergify allows to delete those branches once the pull request has been merged:

pull_request_rules:
  - name: delete head branch after merge
    conditions:
      - merged
    actions:
      delete_head_branch: {}

πŸ– 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.

πŸ₯Ά Removing Stale Reviews πŸ”—

When a pull request is updated, GitHub does not remove the (possibly) outdated reviews approvals or changes request. It’s a good idea to remove them as soon as the pull request gets updated with new commits.

pull_request_rules:
  - name: remove outdated reviews
    conditions:
      - base=master
    actions:
      dismiss_reviews: {}

You could also only dismiss the outdated reviews if the author is not a member of a particular team. This allows to keep the approval if the author is trusted, even if they update their code:

pull_request_rules:
  - name: remove outdated reviews for non trusted authors
    conditions:
      - base=master
      - author!=@myorg/mytrustedteam
    actions:
      dismiss_reviews: {}

πŸ™…οΈ Require All Requested Reviews to Be Approved πŸ”—

If all requested reviews have been approved, then the number of review-requested, changes-requested-reviews-by, and commented-reviews-by should all be 0. You also want to make sure there’s at least one positive review, obviously.

pull_request_rules:
  - name: merge when all requested reviews are valid
    conditions:
      - "#approved-reviews-by>=1"
      - "#review-requested=0"
      - "#changes-requested-reviews-by=0"
      - "#commented-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.

πŸ’Œ Welcoming your Contributors πŸ”—

When somebody that’s not part of your team creates a pull requests, it might be great to give him a few hints about what to expect next. You could write him a little message.

pull_request_rules:
  - name: say hi on new contribution
    conditions:
      - author!=@myorg/regularcontributors
    actions:
        comment:
          message: |
              Welcome to our great project!
              We're delighted to have you onboard <3

🀜 Request for Action πŸ”—

If any event that requires the author of the pull request to edit its pull request happen, you could write a rule that says something about it.

pull_request_rules:
  - name: ask to resolve conflict
    conditions:
      - conflict
    actions:
        comment:
          message: This pull request is now in conflicts. Could you fix it @{{author}}? πŸ™

The same goes if one of your check fails. It might be good to give a few hints to your contributor:

pull_request_rules:
  - name: ask to fix commit message
    conditions:
      - check-failure=Semantic Pull Request
      - -closed
    actions:
        comment:
          message: |
            Title does not follow the guidelines of [Conventional Commits](https://www.conventionalcommits.org).
            Please adjust title before merge.

πŸ‘€ Flexible Reviewers Assignment πŸ”—

You can assign people for review based on any criteria you like. A classic is to use the name of modified files to do it:

pull_request_rules:
  - name: ask jd to review changes on python files
    conditions:
      - files~=\.py$
      - -closed
    actions:
      request_reviews:
        users:
          - jd

You can also ask entire teams to review a pull request based on, e.g., labels:

pull_request_rules:
  - name: ask the security team to review security labelled PR
    conditions:
      - label=security
    actions:
      request_reviews:
        teams:
          - "@myorg/security-dev"
          - "@myorg/security-ops"

πŸ’¬ Running CI pipelines automatically πŸ”—

Some continuous integration systems allow you to trigger jobs by commenting on the pull request. For example, Microsoft Azure allows that using the /AzurePipelines command. You could automate this using Mergify, and for example trigger the job after other CI jobs have passed and at least one developer has reviewed the pull request.

pull_request_rules:
  - name: run Azure CI job once ready to merge
    conditions:
      - "#approved-reviews-by>=1"
      - "check-success=ci/circleci: my_testing_job"
      - -closed
    actions:
      comments:
        message: /AzurePipelines run mypipeline

πŸ“œ Enforcing Pull Request Guidelines πŸ”—

pull_request_rules:
  - name: Guidelines
    conditions:
      - "#title<50"
      - "#body<4096"
      - "#files<100"
      - "body~=(?m)^(Fixes|Related|Closes) (MERGIFY-ENGINE|MRGFY)-"
      - -label=ignore-guidelines
    actions:
      post_check:
        title: Pull request #{{ number }} does{% if not check_succeed %} not{% endif %} follow our guidelines
        summary: |
          My awesome pull request guidelines:

          * The tile must be at least 50 chars long
          * The body must be no longer than 4k chars
          * The PR can't modify more than 100 files
          * Please explain what you're trying to achieve by linking to an issue

          Conditions:

          {{ check_conditions }}

πŸ€– 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 sends automatic security update of your project dependencies.

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

Greenkeeper πŸ”—

Greenkeeper sends automatic update of your npm dependencies.

pull_request_rules:
  - name: automatic merge for Greenkeeper pull requests
    conditions:
      - author=greenkeeper[bot]
      - check-success=Travis CI - Pull Request
      - check-success=greenkeeper/verify
    actions:
      merge:
        method: merge

Renovate πŸ”—

Renovate sends automatic update 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

PyUp πŸ”—

PyUp sends automatic update 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