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.
Maintenance update
This library was developed to make Autorebase possible but focus has shifted to the development of its successor: Autosquash.
This project will thus stop receiving updates.
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:
- Create a
temp
branch frommaster
with POST /repos/:owner/:repo/git/refs.* 017bffc (feature) C * 5b5b6e2 B | * 3c70b13 (HEAD -> temp, master) D |/ * a5c5755 A
- Cherry-pick
5b5b6e2
and017bffc
on top oftemp
withgithub-cherry-pick
.* 6de5ac0 (HEAD -> temp) C * 544d948 B * 3c70b13 (master) D | * 017bffc (feature) C | * 5b5b6e2 B |/ * a5c5755 A
- Check that
feature
's reference is still017bffc
with GET /repos/:owner/:repo/git/refs/:ref or abort by jumping to step 5. - Set
feature
's reference to the same astemp
with PATCH /repos/:owner/:repo/git/refs/:ref.* 6de5ac0 (HEAD -> feature, temp) C * 544d948 B * 3c70b13 (master) D * a5c5755 A
- 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.