tibdex / github-backport

🔙 Backport a pull request using the GitHub REST API

Goal

github-backport backports a pull request using the GitHub REST API.

See Backport to backport a pull request by simply commenting it.

Maintenance update

This library was developed to make Backport possible before it became a GitHub Action.

Backport does not need this dependency anymore so this project will stop receiving updates.

Usage

import { backportPullRequest } from "github-backport";

const example = async () => {
  const backportedPullRequestNumber = await backportPullRequest({
    // The branch upon which the backported pull request should be based.
    base: "master",
    // The description to give to the backported pull request.
    // Defaults to: "Backport #{pullRequestNumber}."
    body: givenBody,
    // The name to give to the head branch of the backported pull request.
    // Defaults to: "backport-{pullRequestNumber}-to-{base}"
    head: givenHead,
    // An already authenticated instance of https://www.npmjs.com/package/@octokit/rest.
    octokit,
    // The username of the repository owner.
    owner,
    // The number of the pull request to backport.
    pullRequestNumber: 1337,
    // The name of the repository.
    repo,
    // The title to give to the backported pull request.
    // Defaults to: "[Backport to {base}] {original pull request title}"
    title: givenTitle,
  });
};

github-backport can run on Node.js and in recent browsers.

Troubleshooting

github-backport uses debug to log helpful information at different steps of the backport process. To enable these logs, set the DEBUG environment variable to github-backport.

How it Works

Backporting a pull request consists in cherry-picking all its commits to another branch. The GitHub REST API doesn't provide direct endpoints to backport a pull request or even to cherry-pick commits. github-backport thus relies on github-cherry-pick to perform all the relevant cherry-pick operations needed to perform a backport.

Step by Step

Let's say we have this Git state:

* 0d40af8 (feature) D
* 8a846f6 C
* b3c3b70 (dev) B
* 55356b7 (HEAD -> master) A

and a pull request numbered #1337 where dev is the base branch and feature the head branch. GitHub would say: "The user wants to merge 2 commits into dev from feature".

To backport #1337 to master, github-backport would then take the following steps:

1. Find out that #1337 is composed of 8a846f6 and 0d40af8 with GET /repos/:owner/:repo/pulls/:number/commits.
2. Create a backport-1337-to-master branch from master with POST /repos/:owner/:repo/git/refs.

   * 0d40af8 (feature) D
   * 8a846f6 C
   * b3c3b70 (dev) B
   * 55356b7 (HEAD -> backport-1337-to-master, master) A
   

3. Cherry-pick 8a846f6 and 0d40af8 on backport-1337-to-master with github-cherry-pick.

   * 1ec51e5 (HEAD -> backport-1337-to-master) D
   * e99200a C
   | * 0d40af8 (feature) D
   | * 8a846f6 C
   | * b3c3b70 (dev) B
   |/
   * 55356b7 (master) A
   

4. Create a pull request where master is the base branch and backport-1337-to-master the head branch with POST /repos/:owner/:repo/pulls.

Atomicity

github-backport is atomic. It will either successfully cherry-pick all the commits and create the backported pull request or delete the head branch created at the beginning of the backport process. There are tests for it.

github-backport's Issues

Support backporting via forks (cross repo PRs)

Sometimes the user performing the backport does not have push access to the primary repository, and the backport branch should therefore be created in a fork.

The Github docs specifies how to create a cross-repo PR:

The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace head with a user like this: username:branch.

I therefore tried to specify the head as:

backportPullRequest({
  head: `some-username:some-branch`,
});

But this throws an error:

refs/heads/some-username:some-branch is not a valid ref name.

Update existing PR instead of throwing "Reference already exists" error

If a backport pull request already exists github-backport throws an error with this message: "Reference already exists"
More details:

{
    "name": "HttpError",
    "status": 422,
    "headers": { ... },
    "request": {
        "method": "POST",
        "url": "https://api.github.com/repos/sqren/backport-demo/git/refs",
        "headers": {
            "accept": "application/vnd.github.v3+json",
            "user-agent": "octokit-rest.js/18.0.3 octokit-core.js/3.1.1 Node.js/10.21.0 (darwin; x64)",
            "authorization": "token [REDACTED]",
            "content-type": "application/json; charset=utf-8"
        },
        "body": "{\"ref\":\"refs/heads/backport-to-6.3\",\"sha\":\"e812829351c83be297d48ad7f4788ccf73c4de26\"}",
        "request": {}
    },
    "documentation_url": "https://docs.github.com/rest/reference/git#create-a-reference"
}

My suggestion is to handle this by updating the existing PR by updating the reference with the latest sha from the base branch. This will make it possible to rebase an existing backport pull request.

This could perhaps be handled explicitly with a new option like allowRebase:

backportPullRequest({
  allowRebase: true
})

or force:

backportPullRequest({
  force: true
})

Typescript error: "Cannot use namespace 'Octokit' as a type." in `lib/index.d.ts`

I'm getting the following error when running tsc

node_modules/github-backport/lib/index.d.ts:9:14 - error TS2709: Cannot use namespace 'Octokit' as a type.

9     octokit: Octokit;
               ~~~~~~~

Found 1 error.

Checkout failing with Shippable

We've started using the app for the Zephyr Project:
zephyrproject-rtos/zephyr#15515

But unfortunately our CI seems to stumble onto an unknown Git ref that we have no idea where is coming from:

https://app.shippable.com/github/zephyrproject-rtos/zephyr/runs/39643/1/console

git checkout -f cherry-pick-backport-15261-to-v1.14-branch-4c757f0a-e2e6-4102-b293-b0a458199a1c --
fatal: invalid reference: cherry-pick-backport-15261-to-v1.14-branch-4c757f0a-e2e6-4102-b293-b0a458199a1c

Any ideas as to where this unknown ref is being fed to Shippable?

Failing backport disables further backports

when a PR is tagged to be backported to multiple branches if one of the backports fails the others are not executed and there is no message by backport bot.

examples can be found here

• qgis/QGIS#9691 (comment)
• qgis/QGIS#30071

removing and readding the labels will trigger further backports. also, it seems that the order with which the labels are set to the PR might be relevant. here an example where one bp failed and one succeeded.

• qgis/QGIS#30869