π Actions π
When a pull request matches the list of π― Conditions of a rule, the
actions configured in that rule are executed by Mergify. The actions should be
put under the actions
key in the pull_request_rules
entry β see
π Configuration File.
The list of available actions is listed below, with their parameters:
assign π
The assign
action assigns users to the pull request.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
list of Template |
The users to assign to the pull request. |
|
|
list of Template |
The users to remove from assignees. |
The list of users in add_users
or remove_users
is based on Template, you can use
e.g. {{author}}
to assign the pull request to its author.
backport π
It is common for software to have (some of) their major versions maintained over an extended period. Developers usually create stable branches that are maintained for a while by cherry-picking patches from the development branch.
This process is called backporting as it implies that bug fixes merged into the development branch are ported back to the stable branch(es). The stable branch can then be used to release a new minor version of the software, fixing some of its bugs.
As this process of backporting patches can be tedious, Mergify automates this mechanism to save developersβ time and ease their duty.
The backport
action copies the pull request into another branch once the
pull request has been merged. The backport
action takes the following
parameter:
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
list of string |
|
The list of branches the pull request should be copied to. |
|
list of string |
|
The list of regexes to find branches the pull request should be copied to. |
|
Boolean |
|
Whether to create the pull requests even if they are conflicts when cherry-picking the commits. |
|
string |
|
The label to add to the created pull requested if it has conflicts and
|
Once the backporting pull request is closed or merged, Mergify will automatically delete the backport head branch that it created.
Warning
If the repository is bigger than 512 MB, the backport
action is only
available for Essential and Premium subscribers.
copy π
The copy
action creates a copy of the pull request targetting other branches.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
list of string |
|
The list of branches the pull request should be copied to. |
|
list of string |
|
The list of regexes to find branches the pull request should be copied to. |
|
Boolean |
|
Whether to create the pull requests even if they are conflicts when cherry-picking the commits. |
|
string |
|
The label to add to the created pull requested if it has conflicts and
|
Warning
If the repository is bigger than 512 MB, the copy
action is only
available for Essential and Premium Plan subscribers.
comment π
The comment
action adds a comment to the pull request.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
The message to write as a comment. |
||
|
Mergify can impersonate a GitHub user to comment a pull request.
If no |
review π
The review
action reviews the pull request.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
string |
|
The kind of review, can be |
|
The message to write as a comment. |
||
|
Mergify can impersonate a GitHub user to review a pull request.
If no |
close π
The close
action closes the pull request without merging it.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
|
The message to write as a comment after closing the pull request. |
delete_head_branch π
The delete_head_branch
action deletes the head branch of the pull request,
that is the branch which hosts the commits. This only works if the branch is
stored in the same repository that the pull request target, i.e., if the pull
request comes from the same repository and not from a fork.
Note
The action will only happen if and when the pull request is closed or merged.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
Boolean |
|
If set to |
dismiss_reviews π
The dismiss_reviews
action removes reviews done by collaborators when the
pull request is updated. This is especially useful to make sure that a review
does not stay when the branch is updated (e.g., new commits are added or the
branch is rebased).
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
Boolean or list of string |
|
If set to |
|
Boolean or list of string |
|
If set to |
|
|
The message to post when dismissing the review. |
label π
The label
action can add or remove labels from a pull request.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
list of string |
|
The list of labels to add. |
|
list of string |
|
The list of labels to remove. |
|
Boolean |
|
Remove all labels from the pull request. |
merge π
The merge
action merges the pull request into its base branch. The
merge
action takes the following parameter:
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
string |
|
Merge method to use. Possible values are |
|
string |
|
If |
|
Boolean, |
|
Determines whether to use Strict Merge:
|
|
string |
|
Method to use to update the pull request with its base branch when Strict Merge is enabled. Possible values:
Note that the |
|
Mergify can impersonate a GitHub user to merge pull request.
If no |
||
|
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 |
||
|
1 <= integer <= 10000 or |
|
This sets the priority of the pull request in the queue when |
|
string |
|
Defines what commit message to use when merging using the
|
Branch Protection Settings π
Note that Mergify will always respect 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.
Defining the 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 add a section in
the pull request body that starts with Commit Message
.
## 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 pull request body or before a new Markdown title.
You can use any available attributes of the pull request in the commit message, by writing using the templating language:
For example:
## Commit Message
{{title}}
This pull request implements magnificient features, and I would like to
talk about them. This has been written by {{author}} and has been reviewed
by:
{% for user in approved_reviews_by %}
- {{user}}
{% endfor %}
Check the Template for more details on the format.
Note
This feature only works when commit_message
is set to default
.
Strict Rebase π
Using the rebase
method for the strict merge has many drawbacks:
It doesnβt work for private forked repositories.
It doesnβt work if Mergify is used as a GitHub Action.
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.
queue π
The queue
action moves the pull request into one of the merge queue defined
in queue_rules
. The queue
action takes the following parameter:
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
string |
The name of the merge queue where to move the pull request. |
|
|
string |
Mergify can impersonate a GitHub user to merge pull request.
If no |
|
|
1 <= integer <= 10000 or |
|
This sets the priority of the pull request in the queued. The pull
request with the highest priority is merged first.
|
|
string |
|
Defines what commit message to use when merging using the
|
request_reviews π
The request_reviews
action requests reviews from users for the pull
request.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
list of string or dictionary of login and weight |
The username to request reviews from. |
|
|
list of string or dictionary of login and weight |
The team name to request reviews from. |
|
|
integer between 1 and 15 |
Pick random users and teams from the provided lists. When
|
Note
GitHub does not allow to request more 15 users or teams for a review.
rebase π
The rebase
action will rebase the pull request against its base branch.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
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 |
Warning
Be aware that rebasing force-pushes the pull request head branch: any change done to that branch while Mergify is rebasing will be lost.
Warning
If the repository is bigger than 512 MB, the rebase
action is only
available for Essential and Premium Plan subscribers.
post_check π
The post_check
action adds an item in a pull request check list. The check
status is success
when all conditions match, otherwise, it is set to
failure
.
Key Name |
Value Type |
Default |
Value Description |
---|---|---|---|
|
The title of the check. |
||
|
The summary of the check. |
As the title
and summary
use on Template, you can
benefit from any pull request attributes e.g. {{author}}
and also these
additional variables:
{{ check_rule_name }}
the name of the rule that triggered this action.
{{ check_succeed }}
isTrue
if all conditions matches otherwiseFalse
{{ check_conditions }}
the list of all conditions with a checkbox marked if the condition match