tibdex/autorebase

🐼 GitHub App to make the Rebase Workflow enjoyable and keep master always green

Autorebase

Autorebase aims to make the Rebase Workflow enjoyable and keep master always green.

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.

Maintenance update

Focus has shifted to the development of Autosquash, the successor of Autorebase.

Indeed:

• The app can now be implemented more simply as a GitHub Action. With a GitHub Action, the Git rebase operation can now be done directly in the CLI instead of doing the complex REST calls made by github-rebase.
• GitHub is more suited for squash and merge than rebase and merge.

Usage

1. 🔐 [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.
2. 🏷️ When you're ready to hand over a pull request to Autorebase, simply add the autorebase label to it.
3. ✨ 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 all the branch protections are respected (mergeable_state === "clean").

One-time /rebase command

Autorebase also supports one-time rebase commands: a collaborator with write permission on a repository can post a /rebase comment on a pull request to rebase it once.

Note: This feature is a convenient way to easily integrate upstream changes such as CI config edits or bug-fixes but it shouldn't be abused as rebasing rewrites the Git history and thus makes collaborating on a pull request harder. See this discussion for more details.

Demo

Rebasing a pull request with out-of-date status checks

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.

---

Autosquashing a suggested commit

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.

FAQ

How Does It Work?

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!

Which Permissions & Webhooks Is Autorebase Using?

Permissions

• 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.

Webhooks

• Issue Comment: to detect one-time /rebase commands.

• Pull request: to detect when the autorebase label 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.closed webhook, Autorebase could listen to push instead. It would allow it to react when a commit was pushed to master without going through a pull request. However, Autorebase would then receive much more events, especially since the rebasing process itself triggers many push events. Thus, to prevent pull requests with the autorebase label 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.

Why Recommend Up-to-Date Status Checks?

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".

Why Rebasing Instead of Squashing/Merging?

Squashing

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.

Merging

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.

Enforcing Rebase Merging

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.

Autosquashing

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.

Why Not Clicking on the “Update Branch” Button Provided by GitHub Instead?

Because it creates merge commits and thus exacerbates the issue explained just above.

When Not to Use Autorebase?

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.

Why Is Autorebase Removing Its Own Label before Rebasing and Then Adding It Back?

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.

How Does Autorebase Compare with the Alternatives?

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	✅	✅	✅

Why the 🐼 Logo?

Because Autorebase loves eating branches 🎍!

autorebase's Issues

Optional rebase + merge --no-ff

Hi!

First of all, thanks a lot for autorebase, it is a really useful project.

Would it be possible to configure autorebase to change its final rebase behaviour?

Now, when a PR has the "autorebase" tag, and the build status is green, autorebase merges the PR with the github api by using the rebase method.

I would like autorebase to do something like: git rebase + git merge --no-ff, to get something like this git history:

I have tried changing autorebase.ts to:

  await octokit.pulls.merge({
    merge_method: "merge",

and it does work, to some extend. autorebase merges the PR when the build is green, but it does not make a rebase first. It does not "detect" that the master branch has evolved and that before merging it should make another rebase.

Would it be possible to make something like this? I am not fluent at all at typescript, but if you give me some hints about what would be needed I can try to develop it.

Thanks a lot!!

What if I want the autorebase feature but not the automerge ?

Hello,

Autorebase looks verycool, but when we merge we deploy, so i don't want merging to be done by this tool.

How can I use only the autorebase feature ?

Rebase failed: Not Found

See celery/celery#5529 (comment).
It's not very clear from the error what went wrong exactly.

Describe whether the service is free or not and how long it will stay around

I know that right now, this GitHub app is free, and at the current level of use it is very cheap to run on Microsoft Lambda.

After you have done calculations based on your expected level of use, you should write in the README some promises or explicit non-promises about whether this app will cost money and whether it will stay running. You can also assure users that even if the hosted GitHub app shut down, they could host it themselves, use an alternative, or go back to running Git commands manually.

Clarify how / why labels are added or removed

Hi,

We've been trying the autorebase bot but witnessing some behaviour that's not clear to us.

When we add the autorebase label to a PR, the bot will rebase the branch when it gets out of date, and then sometimes remove the label. Is this by design?

We've also seen the bot remove the label, rebase the branch, then add the label again. Not sure why it's doing this!

Question concerning usage of this app

I was really excited when I found this app as I thought that it would be a perfect helper for the workflow that we employ on a number of repositories.

However, the first attempt at using it, didn't work as I would have expected:

cake-build/website#609 (comment)

However, I thought that the issue here was due to the fact that the PR was coming from the develop branch on the fork, rather than a branch on the fork. However, I have just tried again with a branch on a fork, and I got the same result:

cake-build/website#635 (comment)

Are my expectations of what this app can do wrong?

Normally, in this situation, the steps that I would follow manually would be:

git clone https://github.com/gep13/website.git
cd website
git remote add upstream  https://github.com/cake-build/website.git
git checkout eazfuscator
git fetch upstream
git rebase upstream/develop
git push -f

And I was hoping that this app would be able to help with this. Is my expectations incorrect?

Public instance down

The public instance has been shutdown:

• It went way over the Zeit Free Plan.
• Focus has shifted to the development of Autosquash, the successor of Autorebase. More explanation here.

Explain the alternatives better in the README

In this section:

• Provide a comparison table with columns such as "rebase or merge" and "tests on latest before merging".
• Mention in the description of Bors that it is better for projects with a high rate of incoming PRs, since the time to run the builds is logarithmic with the number of PRs.

Merge strategies: How to squash'n'merge by default but also allow rebase

Thx for offering this service and github app!

Although I scanned the Readme multiple times it is not clear to me how to support the following use case:
We switched off merging PRs but we let developer pick to squash'n'merge or rebase. The common default is squash'n'merge, but adding the autorebase label always rebases.
How to let the app know that for this specific PR I want it to be squash'n'merged?
Could that be done with another label autosquash?
Or can something be configured or are there more comment options?

I hope I was able to phrase my question n an understandable manner.

Best Christian

Github Rate Limit

I deployed the autorebase app on Zeit.

I receive multiple error concerning GitHub Rate Limit: HttpError: API rate limit exceeded for installation ID XXXX. I'm unsure what steps I need to take to resolve this problem.

Working with CI

I'm currently using autorebase in one of my projects building with CircleCI.

The problem is that autorebase (through its dependencies) creates temporary branch in order to rebase. During the build, Circle tries to checkout this branch, and fails because it has been already removed.

My point is : can we imagine a workaround which lets us to choose the temporary branch name in order to be able to ignore it on CI tools ?

Today, temporary branch name seems to be based on these two lines :

• https://github.com/tibdex/github-cherry-pick/blob/master/src/index.js#L256
• https://github.com/tibdex/shared-github-internals/blob/master/src/git.js#L22

Concurrent rebasing of the same PR

Looking at the source code and at this particular flag, I am not sure it works as expecting.

Your process to manage concurrency is:

1. flag the PR with autorebasing using the call addLabels
2. execute your operation
3. remove the flag

Yet it is unclear if addLabels fails if the label is already present. If not, you could end up having the multiple executors executing step 1.

An alternative would be to:

1. add the label autorebasing
2. remove the label autorebase, using removeLabel
3. execute the operation
4. restore the label autorebase
5. remove the label autorebasing

As removing a label returns a 404 when the label is not present, one and only one process can remove the label autorebase and perform the rebase operation.
One advantage is that the PR cannot be found anymore when listig the candidates.

Again, if addLabels has a way to signal that labels are already present, this is not an issue.

Missing instructions for running tests

I'm trying to deploy autorebase for my organisation. I trying to configure the CI for the project.

I'm having trouble executing the test locally. I figured mostly everything that goes in the .env, but always end up with the following error: HttpError: Resource not accessible by integration

Adding the label does not trigger autorebase

I installed the app, and gave permission to our private repo. But when I add the label autorebase, it doesn't trigger the bot. I am able to see the bot autorebase in the author list. Should we do something additional like adding the webhook manually?

Another thing is that our target branch is staging, not master. Does this cause the problem?

When autorebase does it's job, development status in Jira is outdated for a while

It could of course also be an issue with Jira, but are there any webhooksnot triggered that would be triggered when landing something by clickng the buttons?

With that information I would cross post the issue for Jira (cloud) and cross link the two issues.

Thx in advance