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.