---
title: Setting Up Automatic Merges
description: Learn how to automate your pull request merges with Mergify.
---

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.

## Pre-requisites

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

1. **Mergify Integration**: Your repository must be [configured with
   Mergify](/integrations/github).

2. **Mergify Configuration File**: Automatic merging is configured using a
   [configuration file](/configuration/file-format) 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
   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.

## Setting Up Automatic Merging

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](/configuration/file-format). 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:

   ```yaml
   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.

   :::note
     Any merge conditions defined in your branch protection settings do not need
     to be repeated here. Mergify automatically injects branch protection
     settings in the conditions.
   :::

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](/workflow/actions/merge/) 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.

## Validating All Status Checks

A common condition is to require that "every status check (CI) passes" —
especially before executing the [merge](/workflow/actions/merge) or adding a
pull request to a [queue](/merge-queue/lifecycle).

:::danger
There is no such thing as "every status check" in GitHub.
:::

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.:

```yaml
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.

## Restricting Automatic Merges

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:

   ```yaml
   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:

   ```yaml
   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](/configuration/conditions).

## Automatic Merge and Queues

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](/merge-queue), automatic merge works in tandem with the prioritization
and organization that queues offer. You can leverage the [queue
action](/workflow/actions/queue) 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:

```yaml
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.