The merge action merges the pull request into its base branch.

Mergify always respects the branch protection settings. When the conditions match and the merge action runs, Mergify waits for the branch protection to be validated before merging the pull request.

Mergify also waits for dependent pull requests to get merged first (see โ›“๏ธ Defining Pull Request Dependencies).


Key Name

Value Type


Value Description




Merge method to use. Possible values are merge, squash or rebase.




If method is set to rebase, but the pull request cannot be rebased, the method defined in rebase_fallback will be used instead. Possible values are merge, squash, none. none will report an error if rebase is not possible.


Boolean, smart or smart+fasttrack


Deprecated ๐Ÿ˜ต
Determines whether to use Strict Merge:

  • true enables Strict Merge. The pull request will be merged only once up-to-date with its base branch. When multiple pull requests are ready to be merged, they will all be updated with their base branch at the same time, and the first ready to be merged will be merged; the remaining pull request will be updated once again.

  • smart enables Strict Merge but only update one pull request against its base branch at a time. This allows you to e.g., save CI time, as Mergify will queue the mergeable pull requests and update them serially, one at a time.

  • smart+fasttrack enables Strict Merge with the same behavior as smart, except if the pull request is already in sync with its base branch, the queue is bypassed and the pull request is directly merged.

  • false disables Strict Merge and merge pull requests as soon as possible, without bringing the pull request up-to-date with its base branch.




Deprecated ๐Ÿ˜ต
Method to use to update the pull request with its base branch when Strict Merge is enabled. Possible values:

  • merge to merge the base branch into the pull request.

  • rebase to rebase the pull request against its base branch.

Note that the rebase method has some drawbacks, see Strict Rebase.



Mergify can impersonate a GitHub user to merge pull request. If no merge_bot_account is set, Mergify will merge the pull request itself. The user account must have already been logged in Mergify dashboard once and have write or maintain permission.



Deprecated ๐Ÿ˜ต
For certain actions, such as rebasing branches, Mergify has to impersonate a GitHub user. You can specify the account to use with this option. If no update_bot_account is set, Mergify picks randomly one of the organization users instead. The user account must have already been logged in Mergify dashboard once.


1 <= integer <= 10000 or low or medium or high


Deprecated ๐Ÿ˜ต
This sets the priority of the pull request in the queue when smart Strict Merge is enabled. The pull request with the highest priority is merged first. low, medium, high are aliases for 1000, 2000, 3000.




Deprecated ๐Ÿ˜ต
Defines what commit message to use when merging using the squash or merge method. Possible values are:

  • default to use the default commit message provided by GitHub or defined in commit_message_template or defined in the pull request body (see Defining the Commit Message).

  • title+body means to use the title and body from the pull request itself as the commit message. The pull request number will be added to end of the title.



Template to use as the commit message when using the merge or squash merge method and commit_message is set to default.

โ›“๏ธ Defining Pull Request Dependencies๐Ÿ”—

Open Source
Feature ๐Ÿ’–

You can specify dependencies between pull requests from the same repository. Mergify waits for the linked pull requests to be merged before merging any pull request with a Depends-On: header.

To use this feature, adds 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


This feature does not work for cross-repository dependencies.


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 command to make Mergify realize the dependency has been merged.

Defining the Commit Message๐Ÿ”—

Deprecated ๐Ÿ˜ต


commit_message is deprecated and will be removed on April 25th, 2022. It's replaced by commit_message_template.

To migrate you need to remove the commit_message option from your configuration, then

  • if you used the value default or template, you are done.

  • if you used the value title+body, set commit_message_template to:

{{ title }} (#{{ number }})

{{ body }}
{{ body | get_section("## Commit Message", "") }}

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.

You can use part of the pull request body in the Commit Message Markdown section, by setting it to:

{{ body | get_section("## Commit Message") }}

Then in the pull request body you can use:

## Commit Message

My wanted commit title

The whole commit message finishes at the end of the pull request body or
before a new Markdown title.

The whole commit message finishes at the end of the Markdown section.

You can use any available attributes of the pull request in the commit message, by writing using the templating language:

For example:

## Commit Message


This pull request implements magnificient features, and I would like to
talk about them. This has been written by {{author}} and has been reviewed

{% for user in approved_reviews_by %}
- {{user}}
{% endfor %}

Check the Template for more details on the format.

Or you can also mix template from the configuration and the pull request body by setting commit_message_template to:

{{ body | get_section("## Commit Message") }}

{% for user in approved_reviews_by %}
- {{user}}
{% endfor %}

{% for label in labels %}
- {{label}}
{% endfor %}

Strict Merge๐Ÿ”—

Deprecated ๐Ÿ˜ต


strict merge has been deprecated. The queue action and its queue rules provide a more powerful solution and offer total control of the merge queue.

The strict merge option enables a simple merge queue that prevents merging broken pull requests. That situation can arise when outdated pull requests are being merged in their base branch. For an complete explanation of the problem see this queue action documentation section.

The strict merge option solves that issue by updating any pull request that is not up-to-date with its base branch before being merged. That forces the continuous integration system to test again the pull request with the new code.

When the strict option is enabled, Mergify takes care of merging the target branch in any pull request that is not up-to-date with its target branch. If multiple pull requests are mergeable, they are scheduled to be merged sequentially, and they will be updated on top of each other.

The pull request branch update is only done when the pull request is ready to be merged by the engine, e.g., when all the conditions are validated.

Enabling the Strict Option๐Ÿ”—

To enable strict merge, you need to set the value of strict to true in the merge action. For example:

  - name: automatic merge with strict
      - "#approved-reviews-by>=2"
      - check-success=continuous-integration/travis-ci/pr
        method: merge
        strict: true

Strict Rebase๐Ÿ”—

Using the rebase method for the strict merge has many drawbacks:

  • It doesn't work for private forked repositories.

  • Due to the change of all commits SHA-1 of the pull request, your contributor will need to force-push its own branch if they add new commits.

  • GitHub branch protection of your repository may dismiss approved reviews.

  • GitHub branch protection of the contributor repository may refuse Mergify to force push the rebased pull request.

  • GPG signed commits will lost their signatures.

  • Mergify will use a token from one of the repository member to force-push the branch. GitHub Applications are not allowed to do that so. This is a GitHub limitation that we already have reported โ€” there is not much Mergify can do about that. In order to make this works, Mergify randomly picks and borrows a token from one of your repository member and uses it to force-push the rebased branch. The GitHub UI will show your collaborator as the author of the push, while it actually has been executed by Mergify.