Autorebase is a GitHub App to automatically rebase and merge pull requests.
Autorebase integrates especially well in repositories with branch protection set up to enforce up-to-date status checks.
- 🔌 Install the publicly hosted Autorebase GitHub App on your repository.
- 🔐 [recommended] Protect the branches on which pull requests will be made, such as
master
. In particular, it's best to enable required status checks with the "Require branches to be up to date before merging" option. - 🏷️ When you're ready to hand over a pull request to Autorebase, simply add the "autorebase" label to it.
- ✨ That's it! Pull requests with the "autorebase" label will then be rebased when their base branch moved forward (
mergeable_state === "behind"
) and "rebased and merged" once the required status checks are green and up-to-date (mergeable_state === "clean"
).
Autorebase relies on github-rebase
(which itself relies on github-cherry-pick
) to perform all the required Git operations directly through the GitHub REST API instead of having to clone repositories on a server and executing Git CLI commands.
github-rebase
is the 🗝️ to being able to run Autorebase as a stateless, easy to maintain and cheap to operate, Azure Function/AWS Lambda!
- Repository contents [read & write]: because the rebasing process requires creating commits and manipulating branches.
- Issues [read & write]: to manipulate labels relevant to Autorebase on pull requests.
- Pull requests [read & write]: to merge pull requests.
- Commit statuses [read-only]: to know whether the status checks are green or not.
- Push: to detect when a pull request base branch moved forward.
- Pull request: to detect when the "autorebase" label is added/removed.
- Pull request review: because it can change the mergeable state of pull requests.
- Status: to know when the status checks turn green.
To "keep master
always green".
The goal is to never merge a pull request that could threaten the stability of the base branch test suite.
Green status checks are not enough to offer this guarantee. They must be up-to-date to ensure that the pull request was tested against the latest code on the base branch. Otherwise, you're exposed to "semantic conflicts".
Good pull requests are made of multiple small and atomic commits. You loose some useful information when squashing them in a single big commit. Decreasing the granularity of commits on master
also makes tools such as git blame
and git bisect
less powerful.
Merge commits are often seen as undesirable clutter:
- They make the Git graph much more complex and arguably harder to use.
- They are often poorly named, such as "Merge #1337 into master", repeating what's already obvious.
Besides, even when pull requests are "rebased and merged" (actually merged with the --ff-only
option), you can still, when looking at a commit on master
in the GitHub UI, find out which pull request introduced it.
If you're convinced that rebasing is the best option, you can easily enforce it as the only allowed method to merge pull requests on your repository.
Because it creates merge commits and thus exacerbates the issue explained just above.
Rebasing rewrites the Git history so it's best not to do it on pull requests where several developers are collaborating and pushing commits to the head branch.
- Bors for a more sophisticated rebasing strategy. Bors tries to batch pull requests together and see if the build is still passing on the "agglomerated pull request" before merging the corresponding pull requests. As opposed to Autorebase, Bors is stateful and will perform its required Git operations locally instead of leveraging the GitHub API. It requires storage and thus cannot run as an Azure Function/AWS Lambda: it has much higher operating costs. You also need to host it yourself to use it on private repositories.
- automerge if you don't mind having merge commits in your Git history and either merging pull requests with stale status checks or having to rebase them manually.
- Refined GitHub browser extension and in particular its option to wait for checks when merging a pull request if you don't mind having to keep your browser tab opened waiting for the status checks to be green before merging your pull requests. Like automerge, it comes short when the "Require branches to be up to date before merging" option is enabled.
- TravisCI goes halfway in the good direction: "Rather than build the commits that have been pushed to the branch the pull request is from, we build the merge between the source branch and the upstream branch." but they don't trigger a new build when the upstream/base branch move forward so you still need to rebase your pull requests manually. Besides, it ties you to a specific CI provider as CircleCI, for instance, doesn't do the same "building the pull request from the merge commit provided by GitHub" trick.
Because Autorebase loves eating branches 🎍!