Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
backportRun
✓ import { backportRun } from 'backport'
✗ const { backportRun } = require('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
✓ import type { BackportOptions } from 'backport'
✗ import { BackportOptions } from 'backport'
TypeScript type for configuring the programmatic `backportRun` function. Use `import type` for type-only imports.
run
✓ import { run } from 'backport/cli'
✗ import { run } from 'backport'
Internal CLI execution function. While available, direct programmatic use of `backportRun` is generally preferred for the module API.
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
backport --version
Debug
Known issues
breakingVersion 10.0.0 introduced a breaking change by upgrading the minimum required Node.js version to 20.fixEnsure your Node.js environment is at least v20.0.0. Use a Node Version Manager (like nvm) to switch versions if needed.
affects: >=10.0.0 <10.0.2
breakingVersions 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.fixUpgrade your Node.js environment to version 22.0.0 or higher. The package.json `engines` field specifies this requirement.
affects: >=10.0.2
gotchaThe `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.fixGenerate a GitHub Personal Access Token with appropriate `repo` and `workflow` scopes and add it to `~/.backport/config.json` as `"accessToken": "ghp_YOUR_TOKEN"`.
affects: >=1.0.0
gotchaThe `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.fixBe aware that `backport` doesn't modify your local working directory. Monitor GitHub for the created pull requests and merge them as appropriate.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Missing access token. Please add a personal access token to ~/.backport/config.json
GitHub Personal Access Token is not configured or is invalid.
fixAdd 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.
The `backport` package is not installed globally or `npx` is not being used to execute it.
fixRun `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.
An incompatible Node.js version is being used.
fixUpgrade your Node.js environment to version 22.0.0 or newer. Use a Node Version Manager like `nvm install 22 && nvm use 22`.
Audit
Dependencies
No dependency data recorded yet.