Fast and flexible GitHub action to backport merged pull requests to selected branches.
This can be useful when you're supporting multiple versions of your product. After fixing a bug, you may want to apply that patch to the other versions. The manual labor of cherry-picking the individual commits can be automated using this action.
-x
You can select the branches to backport merged pull requests in two ways:
label_pattern
inputtarget_branches
inputFor each selected branch, the backport action takes the following steps:
cherry_picking
inputThe commits are cherry-picked with the -x
flag.
Add the following workflow configuration to your repository's .github/workflows
folder.
name: Backport merged pull request
on:
pull_request_target:
types: [closed]
permissions:
contents: write # so it can comment
pull-requests: write # so it can create pull requests
jobs:
backport:
name: Backport pull request
runs-on: ubuntu-latest
# Don't run on closed unmerged pull requests
if: github.event.pull_request.merged
steps:
- uses: actions/checkout@v4
- name: Create backport pull requests
uses: korthout/backport-action@v3
Note This workflow runs on
pull_request_target
so thatGITHUB_TOKEN
has write access to the repo when the merged pull request comes from a forked repository. This write access is necessary for the action to push the commits it cherry-picked.
You can also trigger the backport action by writing a comment containing /backport
on a merged pull request.
To enable this, add the following workflow configuration to your repository's .github/workflows
folder.
```yaml name: Backport merged pull request on: pull_request_target: types: [closed] issue_comment: types: [created] permissions: contents: write # so it can comment pull-requests: write # so it can create pull requests jobs: backport: name: Backport pull request runs-on: ubuntu-latest # Only run when pull request is merged # or when a comment starting with `/backport` is created by someone other than the # https://github.com/backport-action bot user (user id: 97796249). Note that if you use your # own PAT as `github_token`, that you should replace this id with yours. if: > ( github.event_name == 'pull_request_target' && github.event.pull_request.merged ) || ( github.event_name == 'issue_comment' && github.event.issue.pull_request && github.event.comment.user.id != 97796249 && startsWith(github.event.comment.body, '/backport') ) steps: - uses: actions/checkout@v4 - name: Create backport pull requests uses: korthout/backport-action@v3 ```
The action can be configured with the following optional inputs:
branch_name
Default: backport-${pull_number}-to-${target_branch}
Template used as the name for branches created by this action.
Placeholders can be used to define variable values.
These are indicated by a dollar sign and curly braces (${placeholder}
).
Please refer to this action's README for all available placeholders.
cherry_picking
Default: auto
Determines which commits are cherry-picked.
When set to auto
, the action cherry-picks the commits based on the method used to merge the pull request.
When set to pull_request_head
, the action cherry-picks the commits from the pull request.
Specifically, those reachable from the pull request's head and not reachable from the pull request's base.
By default, the action cherry-picks the commits based on the method used to merge the pull request.
copy_assignees
Default: false
(disabled)
Controls whether to copy the assignees from the original pull request to the backport pull request. By default, the assignees are not copied.
copy_labels_pattern
Default: ''
(disabled)
Regex pattern to match github labels which will be copied from the original pull request to the backport pull request.
Note that labels matching label_pattern
are excluded.
By default, no labels are copied.
copy_milestone
Default: false
(disabled)
Controls whether to copy the milestone from the original pull request to the backport pull request. By default, the milestone is not copied.
copy_requested_reviewers
Default: false
(disabled)
Controls whether to copy the requested reviewers from the original pull request to the backport pull request. Note that this does not request reviews from those users who already reviewed the original pull request. By default, the requested reviewers are not copied.
experimental
Default:
{
"detect_merge_method": false
}
Configure experimental features by passing a JSON object. The following properties can be specified:
conflict_resolution
Default: fail
Specifies how the action will handle a conflict occuring during the cherry-pick. In all cases, the action will stop the cherry-pick at the first conflict encountered.
Behavior is defined by the option selected.
fail
the backport fails when the cherry-pick encounters a conflict.draft_commit_conflicts
the backport will always create a draft pull request with the first conflict encountered committed.Instructions are provided on the original pull request on how to resolve the conflict and continue the cherry-pick.
downstream_repo
Define if you want to backport to a repository other than where the workflow runs.
By default, the action always backports to the repository in which the workflow runs.
downstream_owner
Define if you want to backport to another owner than the owner of the repository the workflow runs on.
Only takes effect if the downstream_repo
property is also defined.
By default, uses the owner of the repository in which the workflow runs.
github_token
Default: ${{ github.token }}
Token to authenticate requests to GitHub. Used to create and label pull requests and to comment.
Either GITHUB_TOKEN
or a repo-scoped Personal Access Token (PAT).
github_workspace
Default: ${{ github.workspace }}
Working directory for the backport action.
label_pattern
Default: ^backport ([^ ]+)$
(e.g. matches backport release-3.4
)
Regex pattern to match the backport labels on the merged pull request.
Must contain a capture group for the target branch.
Label matching can be disabled entirely using an empty string ''
as pattern.
The action will backport the pull request to each matched target branch. Note that the pull request's headref is excluded automatically. See How it works.
merge_commits
Default: fail
Specifies how the action should deal with merge commits on the merged pull request.
fail
the backport fails when the action detects one or more merge commits.skip
the action only cherry-picks non-merge commits, i.e. it ignores merge commits.
This can be useful when you keep your pull requests in sync with the base branch using merge commits.pull_description
Default:
# Description
Backport of #${pull_number} to `${target_branch}`.
Template used as description (i.e. body) in the pull requests created by this action.
Placeholders can be used to define variable values.
These are indicated by a dollar sign and curly braces (${placeholder}
).
Please refer to this action's README for all available placeholders.
pull_title
Default: [Backport ${target_branch}] ${pull_title}
Template used as the title in the pull requests created by this action.
Placeholders can be used to define variable values.
These are indicated by a dollar sign and curly braces (${placeholder}
).
Please refer to this action's README for all available placeholders.
source_pr_number
Default: ''
(not set)
Specifies the pull request (by its number) to backport, i.e. the source pull request. When set, the action will backport the specified pull request to each target branch. When not set, the action determines the source pull request from the event payload.
target_branches
Default: ''
(disabled)
The action will backport the pull request to each specified target branch (space-delimited). Note that the pull request's headref is excluded automatically. See How it works.
Can be used in addition to backport labels. By default, only backport labels are used to specify the target branches.
In the pull_description
and pull_title
inputs, placeholders can be used to define variable values.
These are indicated by a dollar sign and curly braces (${placeholder}
).
The following placeholders are available and are replaced with:
Placeholder | Replaced with |
---|---|
issue_refs |
GitHub issue references to all issues mentioned in the original pull request description seperated by a space, e.g. #123 #456 korthout/backport-action#789 |
pull_author |
The username of the original pull request's author, e.g. korthout |
pull_description |
The description (i.e. body) of the original pull request that is backported, e.g. Summary: This patch was created to.. |
pull_number |
The number of the original pull request that is backported, e.g. 123 |
pull_title |
The title of the original pull request that is backported, e.g. fix: some error |
target_branch |
The branchname to which the pull request is backported, e.g. release-0.23 |
The action provides the following outputs:
Output | Description |
---|---|
created_pull_numbers |
Space-separated list containing the identifying number of each created pull request. Or empty when the action created no pull requests. For example, 123 or 123 124 125 . |
was_successful |
Whether or not the changes could be backported successfully to all targets. Either true or false . |
was_successful_by_target |
Whether or not the changes could be backported successfully to all targets - broken down by target. Follows the pattern {{label}}=true\|false . |