github-rebase

Goal

github-rebase rebases a pull request using the GitHub REST API. It doesn't merge the pull request, it only rebases its head branch on top of its base branch.

github-rebase has built-in support for autosquashing. Commits with subject starting with fixup! or squash! will be rearranged and squashed automatically.

See Autorebase if you want to automatically rebase and merge green and up-to-date pull requests.

Usage

import { rebasePullRequest } from "github-rebase";

const example = async () => {
  const newHeadSha = await rebasePullRequest({
    // An already authenticated instance of https://www.npmjs.com/package/@octokit/rest.
    octokit,
    // The username of the repository owner.
    owner: "tibdex",
    // The number of the pull request to rebase.
    pullRequestNumber: 1337,
    // The name of the repository.
    repo: "my-cool-project",
  });
};

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

Troubleshooting

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

How it Works

The GitHub REST API doesn't provide a direct endpoint to rebase a pull request without merging it. However, a rebase can be seen as one or multiple cherry-pick operations where the head and base branches would be reversed. github-rebase thus relies on github-cherry-pick to perform all the relevant cherry-pick operations needed to perform a rebase.

Step by Step

Let's say we have this Git state:

* 017bffc (feature) C
* 5b5b6e2 B
| * 3c70b13 (HEAD -> master) D
|/
* a5c5755 A

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

To rebase the pull request, github-rebase would then take the following steps:

1. Create a temp branch from master with POST /repos/:owner/:repo/git/refs.

   * 017bffc (feature) C
   * 5b5b6e2 B
   | * 3c70b13 (HEAD -> temp, master) D
   |/
   * a5c5755 A
   

2. Cherry-pick 5b5b6e2 and 017bffc on top of temp with github-cherry-pick.

   * 6de5ac0 (HEAD -> temp) C
   * 544d948 B
   * 3c70b13 (master) D
   | * 017bffc (feature) C
   | * 5b5b6e2 B
   |/
   * a5c5755 A
   

3. Check that feature's reference is still 017bffc with GET /repos/:owner/:repo/git/refs/:ref or abort by jumpimg to step 5.
4. Set feature's reference to the same as temp with PATCH /repos/:owner/:repo/git/refs/:ref.

   * 6de5ac0 (HEAD -> feature, temp) C
   * 544d948 B
   * 3c70b13 (master) D
   * a5c5755 A
   

5. Delete the temp branch with DELETE /repos/:owner/:repo/git/refs/:ref and we're done!

   * 6de5ac0 (HEAD -> feature) C
   * 544d948 B
   * 3c70b13 (master) D
   * a5c5755 A
   

Atomicity

github-rebase tries as hard as possible to be atomic.

• The underlying cherry-pick operations are atomic.

• The only thing that can go wrong is when a commit is pushed on the pull request head branch between steps 3 and 4 explained above. In that case, the commit that was just pushed won't be part of the pull request head branch anymore. It doesn't mean that this particular commit is completely lost. Commits are immutable and, once pushed, they can always be retrieved from their SHA. See Recovering a commit from GitHub’s Reflog and this Stack Overflow comment that shows that GitHub keeps views of orphan commits in cache for a long time.

  There is no way to fix this issue as the GitHub REST API doesn't provide a compare-and-swap endpoint for updating references like it does for merges. Hopefully the issue should almost never occur since the window during which the head branch is vulnerable usually lasts less than 100 milliseconds (the average GitHub REST API response time).

There are tests for it.