Automated Git Backport CLI Tool

11.0.2 · active · verified Wed Apr 22

Backport is an interactive CLI tool designed to streamline the process of backporting Git commits across multiple release branches. It automates the selection of commits and target branches, handles cherry-picking, pushes changes, and creates pull requests (PRs) on platforms like GitHub. The tool operates in a temporary directory, ensuring it never interferes with a user's local working copy or unstaged changes. Currently at stable version 11.0.2, it sees regular patch and minor releases, maintaining an active development pace. Its key differentiators include an intuitive interactive interface, non-intrusive operation, and a comprehensive workflow from commit selection to PR creation. A GitHub Action wrapping the CLI is also available for CI/CD integration.

Common errors

```
Error: Missing access token. Please add a personal access token to ~/.backport/config.json
```
cause GitHub Personal Access Token is not configured or is invalid.

fix Add a valid `accessToken` to `~/.backport/config.json` with necessary scopes (repo, workflow).
```
Error: The 'backport' command could not be found. Make sure it's installed globally or run with npx.
```
cause The `backport` package is not installed globally or `npx` is not being used to execute it.

fix Run `npm install -g backport` to install globally, or execute with `npx backport` if installed locally.
```
Error: Node.js v18.x is not supported. Please upgrade to Node.js >=22.0.0.
```
cause An incompatible Node.js version is being used.

fix Upgrade your Node.js environment to version 22.0.0 or newer. Use a Node Version Manager like `nvm install 22 && nvm use 22`.

Warnings

breaking Version 10.0.0 introduced a breaking change by upgrading the minimum required Node.js version to 20.
Fix: Ensure your Node.js environment is at least v20.0.0. Use a Node Version Manager (like nvm) to switch versions if needed.
breaking Versions 10.0.2 and later (including all 11.x releases) bumped the minimum required Node.js version to 22.0.0. Older Node versions will cause execution errors.
Fix: Upgrade your Node.js environment to version 22.0.0 or higher. The package.json `engines` field specifies this requirement.
gotcha The `backport` CLI tool requires a GitHub Personal Access Token (`accessToken`) configured in `~/.backport/config.json`. Without it, operations that interact with GitHub APIs (like creating PRs) will fail.
Fix: Generate a GitHub Personal Access Token with appropriate `repo` and `workflow` scopes and add it to `~/.backport/config.json` as `"accessToken": "ghp_YOUR_TOKEN"`.
gotcha The `backport` tool performs all Git operations in a temporary directory (`~/.backport/repositories/`) to avoid interfering with your local working copy. Changes made by `backport` will not be visible in your local repository until the created PRs are merged and you pull them.
Fix: Be aware that `backport` doesn't modify your local working directory. Monitor GitHub for the created pull requests and merge them as appropriate.

Install

npm install backport npm
yarn add backport yarn
pnpm add backport pnpm

Imports

backportRun
wrong:
```
const { backportRun } = require('backport')
```
correct:
```
import { backportRun } from 'backport'
```
Primary programmatic entry point. The package is primarily a CLI tool but exposes a module API. This is ESM-only; CommonJS `require` will not work.
BackportOptions
wrong:
```
import { BackportOptions } from 'backport'
```
correct:
```
import type { BackportOptions } from 'backport'
```
TypeScript type for configuring the programmatic `backportRun` function. Use `import type` for type-only imports.
run
wrong:
```
import { run } from 'backport'
```
correct:
```
import { run } from 'backport/cli'
```
Internal CLI execution function. While available, direct programmatic use of `backportRun` is generally preferred for the module API.

Quickstart

Demonstrates global installation, project-specific configuration with .backportrc.json, global access token setup, and interactive CLI execution.

{
  // .backportrc.json in repository root
  "repoOwner": "your-org",
  "repoName": "your-repo",
  "targetBranchChoices": ["main", "release/1.0", "release/2.0"],
  "autoMerge": true,
  "autoMergeMethod": "squash",
  "branchLabelMapping": {
    "^auto-backport-to-(.+)$": "$1"
  }
}

// ~/.backport/config.json (global config)
{
  "accessToken": "ghp_YOUR_VERY_SECRET_GITHUB_TOKEN"
}

// Terminal
npm install -g backport
npx backport

view raw JSON →