backport reads options from two configuration files:
All file config options be overriden via CLI options.
During installation backport will create an empty configuration file in ~/.backport/config.json. You must update this file with a Github Access Token
Example:
{
"accessToken": "very-secret-token"
}Personal access token. Access tokens can be created here: https://github.com/settings/tokens
Please select the necessary access scopes:
For public and private repos (recommended)
For public repos only
If a merge conflicts occurs during backportin your editor of choice will be opened to make it easier for you to resolve the conflict
{
"editor": "code"
}A .backportrc.json config file should be added to the root of each project where backport is used. This is useful for sharing configuration options with other project contributors.
Example:
{
"repoOwner": "elastic",
"repoName": "kibana",
"targetBranchChoices": ["6.x", "6.3", "6.2", "6.1", "6.0"],
"targetPRLabels": ["backport"]
}Name of repository
{
"repoName": "kibana"
}Owner of repository (Github organization or Github username)
{
"repoOwner": "elastic"
}List of target branches the user can select interactively.
{
"targetBranchChoices": ["6.3", "6.2", "6.1", "6.0"]
}The array can contain branch names as strings or objects that also contains the field checked which indicates whether the branch should be pre-selected. It is useful to pre-select branches you often backport to.
{
"targetBranchChoices": [
{ "name": "6.3", "checked": true },
"6.2",
"6.1",
"6.0"
]
}The following options can be used in both the global config, project config, and passed in through CLI.
Add assignees to the target pull request
{
"assignees": ["sorenlouv"]
}By default only commits from the authenticated user are displayed. To see commits from another user use --author john.doe. To see commits from any user use --all (cli-only flag).
{
"author": "sorenlouv"
}To view commits form all users (equivalent to backport --all):
{
"author": null
}Automatically add the current user as assignee to the target pull request.
Default: false
{
"autoAssign": true
}Automatically merge the backport pull request when true.
Default: false
{
"autoMerge": true
}When autoMerge: true the backport pull request will be merged with one of the following methods: merge, rebase, squash.
Default: merge
{
"autoMergeMethod": "squash"
}The official way to run backport is by installing it globally and running backport. There are however many other ways to run it. It can be installed locally and then run with npx backport/yarn backport or wrapped in a custom script and run like a node.js application node scripts/backport.
If you are using a non-standard way to run backport it is useful to add that here, to ensure that the Github comments posted by the backport tool includes the correct command.
Important: Since this command will be included in status comments on Github, it must NOT include sensitive information, like an access token.
Example of how backportBinary is used:
Default: backport
{
"backportBinary": "node scripts/backport"
}Automatically detech which branches a pull request should be backported to, based on the pull request labels.
{
"branchLabelMapping": {
"^v7.8.0$": "7.x",
"^v(\\d+).(\\d+).\\d+$": "$1.$2"
}
}Note: backslashes must be escaped.
When running backport on CI (aka in non-interactive mode) any commit conflicts will result in the backport being aborted. When commitConflicts: true even files with conflicts will be committed and a backport PR created. It is then up to a user to manually resolve the conflict, If auto-merge is enabled, this will be disabled for this PR specifically to avoid merging unresolved conflicts.
{
"commitConflicts": true
}Clone repository into custom directory
Default: ~/.backport/repositories/
{
"dir": "/my/custom/tmp/repo/location"
}Only display commits newer than the specified date
Only display commits older than the specified date
true: Create backport branch in users own fork
false: Create backport branch in the origin repository
Default: true
{
"fork": false
}Hostname for Github.
Default: github.com
{
"gitHostname": "github.my-private-company.com"
}Base url for Github's REST (v3) API
Default: https://api.github.com
{
"githubApiBaseUrlV3": "https://api.github.my-private-company.com"
}Base url for Github's GraphQL (v4) API
Default: https://api.github.com/graphql
{
"githubApiBaseUrlV4": "https://github-enterprise.acme-inc.com/api"
}When backporting a merge commit the parent id must be specified. This is directly passed to git cherry-pick and additional details can be read on the Git Docs
Examples:
- Defaults to 1 when no parent id is given:
backport --mainline - Specifying parent id:
backport --mainline 2
Number of commits that will be listed for the user to choose from.
Default: 10
{
"maxNumber": 20
}true: you will be able to select multiple commits to backport. You will use <space> to select, and <enter> to confirm you selection.
false: you will only be able to select a single commit. You will use <enter> to confirm the selected item.
Default: false
true: you will be able to select multiple branches to backport to. You will use <space> to select, and to confirm you selection.
false: you will only be able to select a single branch. You will use <enter> to confirm the selected item.
Default: true
Only list commits touching files under the specified path
{
"commitPaths": ["my/folder"]
}Title for the target pull request Template values:
{{sourceBranch}}: Branch the commit is coming from (usuallymain){{targetBranch}}: Branch the backport PR will be targeting{{sourcePullRequest}}: Original pull request object (see interface){{commitMessages}}: Message of backported commit. For multiple commits the messages will be separated by pipes (|).{{commits}}: A list of commits (interface)
Default: "[{{targetBranch}}] {{commitMessages}}"
Example: Use original PR title prefixed by branch
{{targetBranch}} {{sourcePullRequest.title}}
Example
{
"prTitle": "{{commitMessages}} backport for {{targetBranch}}"
}See source code for more examples
Description for the target pull request The description uses the handlebars templating engine:
{{sourceBranch}}: Branch the commit is coming from (usuallymain){{targetBranch}}: Branch the backport PR will be targeting{{commitMessages}}: Message of backported commit. For multiple commits the messages will be separated by new lines (|).{{defaultPrDescription}}: The default PR description. Using this makes it easy to append and prepend text to the existing description{{commits}}: A list of commit objects (see commit interface)
Example: List commits
{{#each commits}}
{{shortSha this.sourceCommit.sha}} {{this.sourceCommit.message}}
{{/each}}
Example: append test to default description
For people who often want to append the same text, they can create a bash alias:
alias backport-skip-ci='backport --pr-description "{defaultPrDescription} [skip-ci]"'See source code for more examples
Filter source pull requests by any Github query. Text with whitespace must contain escaped quotes.
{
"prFilter": "label: \"Backport Needed\""
}Publish a status comment to the source pull request if the backport was aborted
Default: False
{
"publishStatusCommentOnSuccess": false
}Publish a status comment to the source pull request if all backports succeeded
Default: true
{
"publishStatusCommentOnSuccess": false
}Publish a status comment to the source pull request if some backports failed
Default: false
{
"publishStatusCommentOnFailure": false
}Backport a pull request by specifying its number
Change the author of the backported commit to the current user
Add reviewers to the target pull request
Backport a commit by specifying its commit sha
Pass the --signoff option to the cherry-pick command
By default the list of commits will be sourced from the repository's default branch (mostly "master"). Use sourceBranch to list and backport commits from other branches than the default.
Default: master (unless the default branch on Github is changed)
{
"sourceBranch": "7.x"
}Assign the same reviewers to the target pull request that were assigned to the original (source) pull request.
{
"copySourcePRReviewers": false
}Copies all labels from the original (source) pull request to the backport (target) pull request.
{
"copySourcePRLabels": false
}Labels that will be added to the source (original) pull request. This can be useful if you, at a later time, want to find the PRs that were already backported.
{
"sourcePRLabels": ["was-backported"]
}Overrides targetBranchChoices so instead of displaying a prompt with target branches to choose from, the selected commit(s) will be backported directly to the branches defined in targetBranches
{
"targetBranches": ["7.x", "7.7"]
}Labels that will be added to the target (backport) pull request. This can be useful if you, at a later time, want to find the backport PRs.
{
"targetPRLabels": ["backport", "apm-team"]
}Branch name to use for the backport PR Template values:
{{targetBranch}}: Branch the backport PR will be targeting{{sourcePullRequest}}: Original pull request object (see interface){{refValues}}: Name representing the original commit/PR,commit-<hash>orpr-<pr number>respectively.
Default: backport/{{targetBranch}}/{{refValues}}
Example
{
"backportBranchName": "{{targetBranch}}-{{refValues}}-backport"
}See source code.