---
title: Backport
description: Copy a pull request to another branch once it is merged.
---

import ActionOptionsTable from '../../../../components/Tables/ActionOptionsTable';

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.

:::caution
  Please make sure the branches specified in the backport action exist and
  you have the necessary access permissions. If the branch does not exist or
  you don't have the required permissions, the action will fail.
:::

## 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.

<ActionOptionsTable def="BackportActionModel" />

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

### Using Labels to Backport

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

```yaml
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

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:

```yaml
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

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:

```yaml
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
```

### Impersonating the Original Author

If you want to create a backport impersonating the original pull request
author, you can configure the default `backport` actions parameter to use a
`bot_account` with the original pull request author account.

```yaml
defaults:
  actions:
    backport:
      bot_account: {{ author }}
```

:::note
  Pull request author will need to log at least once in the Mergify dashboard
  for a pull request to be created on their behalf.
:::