Setting Up Automatic Merges

Mergify’s automatic merging is a powerful feature designed to help maintainers save time and keep their repositories up-to-date efficiently. It automates the process of merging pull requests (PRs) once they meet your specified conditions, thereby reducing the need for manual intervention.

This capability is particularly beneficial in scenarios where numerous PRs are regularly opened, such as in open-source projects or in teams practicing continuous integration. By utilizing automatic merging, you can ensure that PRs get merged promptly once they’re ready, helping to maintain a smooth and fast-paced development workflow.

Before setting up automatic merges, ensure you meet the following requirements:

1. Mergify Integration: Your repository must be configured with Mergify.

2. Mergify Configuration File: Automatic merging is configured using a configuration file in your repository. This file contains the rules and actions Mergify will follow, including the conditions for automatic merging.

3. Branch Protection Rules: Review any branch protection rules that might prevent automatic merging. For example, make sure that required status checks are configured correctly and that they pass before Mergify tries to merge your PRs.

To enable automatic merging in a Mergify-powered repository, follow these steps:

1. Create or Edit the Mergify Configuration File: Navigate to your repository and create or open the Mergify configuration file. This file is where you define all your Mergify rules.

2. Define a Pull Request Rule for Merging: In the configuration file, you will need to create a rule that tells Mergify when to automatically merge a pull request. Here’s an example of a basic rule:

   pull_request_rules:
     - name: Automatic merge when CI passes and reviews approve
       conditions:
         - "#approved-reviews-by >= 1"
         - check-success = CI # replace "CI" with the name of your CI status check
       actions:
         merge:
           method: merge

   In this example, a pull request is automatically merged when it has at least one approved review and the CI status check passes.

3. Customize Your Merge Action: The merge action in the rule can be customized further. You can specify the method to use for merging (merge, rebase, or squash), or specify commit message options. Check the merge action documentation for more information on these options.

4. Save and Commit Your Changes: Once you’ve added and customized your merge rule, commit the changes to your configuration file and push it to your repository. We recommend merging it via a pull request so Mergify can validate the configuration file.

With these settings, Mergify will automatically merge eligible pull requests based on the conditions you’ve specified.

A common condition is to require that “every status check (CI) passes” — especially before executing the merge or adding a pull request to a queue.

Here’s why:

1. Each pull request can have its own custom list of status checks. This means the list of “status check” does not exist and is not common to all pull requests.

2. On creation, or when a new commit is pushed, a pull request has no status check.

3. 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 have build in their name (see point 1. and 2.above).

Such conditions won’t do what you want them to do.

In some cases, you might want to restrict automatic merges based on certain conditions. This can be useful to enforce code quality standards, ensure all necessary checks have passed, or prevent merging of pull requests that do not meet certain criteria. Here’s how you can set this up:

1. Specify the Restrictive Conditions: In your pull request rule, you can specify conditions that a pull request must meet before it can be merged. This can include anything from passing status checks to having a certain number of approved reviews.

   Here’s an example that restricts automatic merging to pull requests that have at least two approved reviews and all status checks passing:

   pull_request_rules:
     - name: Automatic merge when CI passes and reviews approve
       conditions:
         - "#approved-reviews-by >= 2"
         - check-success = CI # replace "CI" with the name of your CI status check
       actions:
         merge:
           method: merge
   

2. Use Negative Conditions: You can also use negative conditions to prevent automatic merging. For instance, you might want to prevent merging if certain labels are present. Here’s an example:

   pull_request_rules:
     - name: Automatic merge when CI passes and reviews approve, unless 'do-not-merge' label is present
       conditions:
         - "#approved-reviews-by >= 2"
         - check-success = CI # replace "CI" with the name of your CI status check
         - label != do-not-merge
       actions:
         merge:
           method: merge
   

   In this case, the label!=do-not-merge condition prevents automatic merging if the do-not-merge label is attached to the pull request.

Remember, conditions are highly flexible and can be adapted to suit your project’s specific needs. For a full list of available conditions, refer to the conditions documentation.

When automatic merging is enabled, pull requests are merged as soon as all the conditions specified in your rule are met. In the context of Mergify’s Merge Queue, automatic merge works in tandem with the prioritization and organization that queues offer. You can leverage the queue action to put pull requests in the merge queue rather than merging directly.

Here’s an example of how this might look in your Mergify configuration file:

pull_request_rules:
  - name: Automatic merge when CI passes and reviews approve
    conditions:
      - "#approved-reviews-by >= 2"
      - check-success = CI # replace "CI" with the name of your CI status check
    actions:
      queue:
        merge_method: merge

In this case, when a pull request meets the conditions (#approved-reviews-by >= 2 and check-success = CI), it is added to the merge queue. Once it’s at the front of the queue, Mergify will automatically merge it into the target branch and then move on to the next pull request in the queue.

This combination of queues and automatic merging allows for a more efficient and organized way of managing your pull requests, ensuring that pull requests are merged in a timely and prioritized manner.