Skip to content
This repository has been archived by the owner on Sep 6, 2020. It is now read-only.
/ github-backport Public archive

🔙 Backport a pull request using the GitHub REST API

License

Notifications You must be signed in to change notification settings

tibdex/github-backport

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

npm version build status

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.

About

🔙 Backport a pull request using the GitHub REST API

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published