Autorebase aims to make the Rebase Workflow enjoyable and keep master always green. Try it!
Autorebase is a GitHub App, based on Probot, which automatically rebases and merges pull requests.
It 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
autorebaselabel to it. - ✨ That's it! Pull requests with the
autorebaselabel will then be rebased when their base branch moved forward (mergeable_state === "behind") and "rebased and merged" once all the branch protections are respected (mergeable_state === "clean").
This pull request has two commits and targets the master branch. The master branch has a required status check that must be up to date before merging a pull request on it. After adding the autorebase label, Autorebase automatically rebases the pull request on top of master. The pull request's branch is now up to date with master. As soon as a new successful status check is added to the pull request's last commit, Autorebase merges the pull request.
Again, this pull request has two commits and targets the master branch. Here, a reviewer made a suggested change on its first commit. We accept this suggestion and name the resulting commit "fixup! Addition". Where "Addition" is the subject of the first commit. After adding the autorebase label, Autorebase automatically rebases the pull request on top of master, autosquashing the suggested commit with the first one. Autorebase will then merge the pull request. We can see that two commits (and not three!) have landed on master and that the diff of the "Addition" commit is the suggested one.
Note: We could also have named the fixup commit with the first commit's entire or abbreviated SHA. Meaning that "fixup! 00fac8d" would have worked too.
Autorebase relies on github-rebase 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, GitHub App!
- Repository contents [read & write]: because the rebasing process requires creating commits and manipulating branches.
- Issues [read & write]: to search for pull requests to rebase or merge and add to manipulate labels on pull requests.
- Pull requests [read & write]: to merge pull requests.
- Checks & Commit statuses [read-only]: to know whether the status checks are green or not.
-
Pull request: to detect when the
autorebaselabel is added/removed and when a pull request is closed. Indeed, closing a pull request by merging its changes on its base branch may require rebasing other pull requests based on the same branch since they would now be outdated.Note: Instead of listening to the
pull_request.closedwebhook, Autorebase could listen topushinstead. It would allow it to react when a commit was pushed tomasterwithout going through a pull request. However, Autorebase would then receive much more events, especially since the rebasing process itself triggers manypushevents. Thus, to prevent pull requests with theautorebaselabel to get stuck behind their base branch, try not to push commits to these base branches without going through pull requests. -
Pull request review: because it can change the mergeable state of pull requests.
-
Check run & 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.
See also this Bitbucket article for a more in-depth comparison between the merge and rebase workflows. It lists traceability as the main advantage of the merge workflow. However, on GitHub, 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 web app, 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.
Autorebase has built-in autosquashing support. It will come in handy to automatically fixup/squash these commits added on pull requests after a reviewer requested changes.
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.
Autorebase can receive multiple webhooks for the same pull request in a short period of time.
Letting these invocations try to concurrently rebase that pull request is unnecessary since only one attempt would succeed anyway.
To prevent this from happening, we use the autorebase label as a lock.
Before Autorebase starts rebasing a pull request, it will acquire the lock by removing the label.
Other concurrent Autorebase invocations won't be able to do the same thing because the GitHub REST API prevents removing a label from a pull request that doesn't have it.
| Name | No Merge Commits | Stateless (no Database Required) | Ensure Up-to-Date Status Checks Without Manual Intervention / Test on Latest Before Merging | Comments |
|---|---|---|---|---|
| Bors | ❌ | ❌ | ✅ | Bors provides a more sophisticated rebasing strategy. It 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. Bors might be better for projects with long/expensive CI builds and a high rate of incoming pull requests, since the time to run the builds is, in the best case, logarithmic with the number of pull requests. |
| automerge | ❌ | ✅ | ❌ | |
| Refined GitHub browser extension | ❌ | ✅ | ❌ | Refined GitHub has an 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. |
| TravisCI | ✅ | ✅ | ❌ | 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 since CircleCI, for instance, doesn't do the same "building the pull request from the merge commit provided by GitHub" trick. |
| Autorebase | ✅ | ✅ | ✅ |
Because Autorebase loves eating branches 🎍!