---
title: Merge
description: Automate the merging of your pull requests.
---

import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';
import { Image } from "astro:assets"
import branchProtectionConditionsScreenshot from "../../../images/workflow/actions/merge/branch-protections-injection.png"

The `merge` action allows Mergify to automatically merge pull requests when
certain conditions are met. This can significantly streamline your workflow by
reducing the need for manual intervention.

Whatever your conditions are, Mergify might inject extra conditions for the
merge action to take place:

- Mergify always respects the [branch protection settings](#branch-protection-conditions)

- Mergify always respect [pull request dependencies](#pull-request-dependencies)

- Mergify always respect the [merge date](#merge-date)

- Mergify allows merging pull request modifying its configuration file by
  default. But Mergify will always check whether these changes are
  valid or not, to avoid merging broken configurations.

## Branch Protection Conditions

GitHub provides [branch
protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
and [rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)
settings that allow to enforce certain restrictions when pushing commits to
your repository.

Mergify automatically injects those conditions in your rules, though,
they could be bypassed.
(see
[branch_protection_injection_mode](/configuration/file-format/#queue-rules).
For example, if you request your pull request to be approved by at least
one person, Mergify will inject the `#approved-reviews-by >= 1` condition.

<Image src={branchProtectionConditionsScreenshot} alt="Mergify Branch Protection Condition Injection" />

If you're using rulesets instead of the classic branch protections, you can also bypass
the injection of those conditions by setting Mergify as a bypass actor with the bypass mode set to `exempt`.
With all other bypass modes, Mergify will inject the conditions in your rules.

Note that branch protection supports has some limitations. For example, GitHub
does not provide an API to support [code
owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
which makes it unreliable in certain circumstances.

The following protection settings are only partially supported by Mergify:

- Require status checks to pass before merging;
- Require branches to be up to date before merging;
- Require review from Code Owners;
- Require linear history;
- Require conversation resolution before merging;
- Require approvals.

## Pull Request Dependencies

You can specify dependencies between pull requests from the same repository,
or from other repositories with Mergify installed within your organization.
Mergify waits for the linked pull requests to be merged before merging any pull
request with a `Depends-On:` header.

To use this feature, add the `Depends-On:` header to the body of your pull
request:

```text
New awesome feature 🎉

To get the full picture, you may need to look at these pull requests:

Depends-On: #42
Depends-On: https://github.com/organization/repository/pull/123
Depends-On: https://github.com/organization/other-repository/pull/456
Depends-On: organization/test-repository#789
```

In this example, the pull request will only be merged when the pull
request #42, #123, #456 from `other-repository` and #789 from
`test-repository` are merged.

:::caution
  If the dependency happens between pull requests targeting different branches,
  the evaluation of the dependent will not be automatic. You might need to use
  the [refresh](/commands/refresh) command to make Mergify realize the
  dependency has been merged.
:::

## Merge Date

You can specify a date after which you want a pull request to be merged with a
`Merge-After:` header. Mergify will wait for the date and time to be passed
before merging your pull request.

To use this feature, add the `Merge-After:` header to the body of your pull
request, followed by the date in the [timestamp
format](/configuration/data-types#timestamp).

For example, if a pull request body contains:

```text
Merge-After: 2023-04-18 18:20
```

The pull request will only be merged after April, 18th 2023 at 18:20 UTC, if
all other merge conditions are satisfied.

## Parameters

<ActionOptionsTable def="MergeActionModel" />

## Examples

### Automatic Merge

In this example, Mergify will automatically merge (using the squash method) any
pull request that has passed its CI checks and has at least 2 approved reviews.

```yaml
pull_request_rules:
  - name: automatic merge when CI checks pass and at least 2 approved reviews
    conditions:
      - check-success = test
      - "#approved-reviews-by >= 2"
    actions:
      merge:
        method: squash
```

### Using Commit Message Template

When a pull request is merged using the squash or merge method, you can
override the default commit message. To that end, you need to set
`commit_message_template`. This setting is a
[template](/configuration/data-types#template), which means you can use
attributes of the pull request to build the content of the commit message.

```yaml
pull_request_rules:
  - name: automatic merge when CI checks pass and at least 2 approved reviews
    conditions:
      - check-success = test
      - "#approved-reviews-by >= 2"
    actions:
      merge:
        method: squash
        commit_message_template: |
        {{ title }} (#{{ number }})

        {{ body }}
```

This configuration makes sure the commit message for the squash commit is taken
from the title, includes the pull request number and uses the body as the
message. Merging the pull request results in a single squashed commit with the
message:

```text
Fix some bug (#123)

This fixes some bug I found while testing the app.
```

For example, you could include reviewers of a pull request in the commit
message of a pull request:

```yaml
pull_request_rules:
  - name: automatic merge when CI checks pass and at least 2 approved reviews
    conditions:
      - check-success = test
      - "#approved-reviews-by >= 2"
    actions:
      merge:
        method: squash
        commit_message_template: |
{{ title }} (#{{ number }})

{{ body }}

{% for user in approved_reviews_by %}
Approved-By: {{user}}
{% endfor %}
```

which would result to the following commit message:

```text
Fix some bug (#123)

This fixes some bug I found while testing the app.

Approved-By: jd
Approved-By: sileht
```