Merge

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

• Mergify always respect pull request dependencies

• Mergify always respect the 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.

Mergify automatically reads your GitHub branch protections and rulesets and injects them as merge conditions. For example, if you require at least one approved review, Mergify injects the #approved-reviews-by >= 1 condition.

For details on how injection works, which ruleset rules are compatible, known incompatibilities, and how to configure bypass actors, see GitHub Rulesets Compatibility.

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:

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.

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.

For example, if a pull request body contains:

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

The pull request will only be merged after April, 18th 2023 at 18

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.

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

When merging with the merge or squash method, the commit_message_format setting controls the title, body, and trailers of the resulting commit:

commit_message_format:
  title: inherit            # inherit | pr-title              (default: inherit)
  body:  inherit            # inherit | pr-body | empty       (default: inherit)
  trailers: []              # subset of [co-authored-by, approved-by, merged-by]

commit_message_format is accepted under queue_rules, actions.merge, and defaults. Omit it to let your repository’s GitHub settings render the entire commit.

• inherit (default): Mergify does not send a title; your repository settings render it.

• pr-title: use the pull request title with the PR number appended: {title} (#{number}).

• inherit (default): Mergify does not send a body; your repository settings render it.

• pr-body: use the pull request description.

• empty: produce an empty body. Useful when you only want trailers.

trailers is an ordered list. Mergify appends one trailer block to the commit body, separated by a blank line:

All three follow the canonical kernel-style Name <email> shape and are parseable by git interpret-trailers. Co-authored-by continues to render as a co-author badge in the GitHub UI.

• commit_message_format and commit_message_template cannot be set on the same rule.

• body: inherit cannot be combined with non-empty trailers, because Mergify must not override the body to append trailers.

GitHub-style commit, with the pull request title in the subject and the pull request description as the body:

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_format:
          title: pr-title
          body: pr-body

Merging a pull request titled “Fix some bug” with the description “This fixes some bug I found while testing the app.” produces:

Fix some bug (#123)

This fixes some bug I found while testing the app.

The remaining variants show only the commit_message_format block; nest it under actions.merge, queue_rules[], or defaults.

Title only, no body content:

commit_message_format:
  title: pr-title
  body: empty

Pull request description plus an Approved-by: trailer block:

commit_message_format:
  title: pr-title
  body: pr-body
  trailers:
    - approved-by

resulting in:

Fix some bug (#123)

This fixes some bug I found while testing the app.

Approved-by: jdoe <12345+jdoe@users.noreply.github.com>
Approved-by: jsmith <67890+jsmith@users.noreply.github.com>

Trailer-only commit, useful when you want every merge to carry a Merged-by: line and nothing else:

commit_message_format:
  title: pr-title
  body: empty
  trailers:
    - merged-by

The legacy commit_message_template setting is a template that renders the entire commit message. commit_message_format covers the common patterns declaratively, with predictable output and no template engine.

Most existing templates map directly:

For example, this template that appends an Approved-by: line per reviewer:

commit_message_template: |
  {{ title }} (#{{ number }})

  {{ body }}

  {% for user in approved_reviews_by %}
  Approved-by: {{ user }}
  {% endfor %}

becomes:

commit_message_format:
  title: pr-title
  body: pr-body
  trailers:
    - approved-by