Backport

Copy a pull request to another branch once it is merged.

The backport action enables you to automatically create a backport of a merged pull request. When the conditions you specify are met, Mergify will create a new pull request to merge the changes into the specified base branch.

The backport action is extremely useful for maintaining older versions of your project. It helps automate the process of applying bug fixes or other changes from the main branch to other branches.

Note that in case of a conflict during the backport, Mergify will create a pull request with the conflict; you will have to resolve it manually. You can change this behaviour using the ignore_conflicts option.

Parameters

Section titled Parameters

The backport action takes a list of branches to which the changes from the merged pull request will be backported. The branch names should be specified as strings.

Key nameValue typeDefault
assigneeslist of template

Users to assign the newly created pull request to. As the type is a data type template, you could use, e.g., {{author}} to assign the pull request to its original author.

bodytemplate
|
  {{ body }}
This is an automatic backport of pull request #{{number}} done by [Mergify](https://mergify.com).

The pull request's body.

bot_accounttemplate or null
null

Mergify can impersonate a GitHub user to copy a pull request. If no bot_account is set, Mergify copies the pull request itself.

brancheslist of Branch Name

The list of branches the pull request should be copied to.

ignore_conflictsboolean
true

Whether to create the pull requests even if there are conflicts when cherry-picking the commits.

label_conflictsstring
conflicts

The label to add to the created pull request if it has conflicts and ignore_conflicts is set to true.

labelslist of string

The list of labels to add to the created pull requests.

merge_conflict_stylemerge or diff3
merge

Style used by git when displaying merge conflicts

regexeslist of

The list of regexes to find branches the pull request should be copied to.

report_modelist of check or comment
- check

List of reporting modes for the action's result.

titletemplate
"{{ title }} (backport #{{ number }})"

The pull request's title.

As the title and body are templates, you can leverage any pull request attributes to use as content, e.g., {{author}}.

Note that the commits attribute here will be the list of cherry picked commits.

On top of that, you can also use the following additional variables:

  • {{ destination_branch }}: the name of the destination branch.

  • {{ cherry_pick_error }}: the cherry pick error message if any (only available in body).

Examples

Section titled Examples

Using Labels to Backport

Section titled Using Labels to Backport

Below is an example of how to use the backport action:

pull_request_rules:
  - name: backport patches to the release branch and assign to original author
    conditions:
      - label = backport
    actions:
      backport:
        branches:
          - "release-1.0"
          - "release-1.1"
        assignees:
          - "{{ author }}"

Combining Automatic Merge

Section titled Combining Automatic Merge

You can also combine the backport action with other actions like merge. This can be useful in scenarios where you want to automatically backport and merge pull requests that fulfill certain conditions.

Here’s an example:

pull_request_rules:
  - name: backport patches to the release branch
    conditions:
      - label = backport
    actions:
      backport:
        branches:
          - "release-1.0"
          - "release-1.1"

  - name: automatically merge backport if they pass tests
    conditions:
      - author = mergify[bot]
      - base ~= ^mergify/bp/
      - head ~= ^release-1.
      - check-success = continuous-integration
    actions:
      merge:
        method: merge

In this configuration, a pull request is backported when it has the label backport. Then, when the backport is created and passes the check named continuous-integration, it will be automatically merged.

Implementing -x option

Section titled Implementing -x option

If you are used to the -x option of git cherry-pick that includes which commits has been cherry-picked, you can implement the same thing with Mergify:

pull_request_rules:
  - name: backport patches to the stable branch
    conditions:
      - label = backport
    actions:
      backport:
        body: |
          {{ body }}

          {% for c in commits %}
          (cherry picked from commit {{ c.sha }})
          {% endfor %}
        branches:
          - stable