title: GerritBot

GerritBot is a tool used for importing GitHub Pull Requests (PRs) into Gerrit for code review. It was created because the Go team does all its reviews in Gerrit, but we'd like to allow a more common workflow for contributing code via GitHub PRs.

Table of Contents

Workflow

  • A user can upload a GitHub PR against any of our GitHub repos just as they would with any other GitHub project that accepts PRs
  • The PR changes will then be imported by GerritBot and a message will be posted to the GitHub PR containing a link to the Gerrit review
  • All comments are handled within Gerrit. Any comments on the GitHub PR will be ignored
  • The PR author can continue to upload commits to the branch used by the PR in order to address feedback from Gerrit
  • Any changes to the commit message must be done by editing the title and description of the GitHub PR, and not via Gerrit or git. (See FAQ below for details).
  • Draft PRs are imported as WIP
  • Once the code is ready to be merged, a maintainer will submit the change on Gerrit and GerritBot will close the issue
  • Similarly, if a change is closed or abandoned on Gerrit, the corresponding PR will be closed

Frequently Asked Questions

I need a Google account to sign up for Gerrit? Why can't I sign in using my GitHub account?

You need a Gmail or other Google account to register for Gerrit. This is a limitation of the infrastructure that runs our Gerrit instances and is out of our control, plus you already need a Google account to sign our CLA, a requirement for us to accept your contribution in the first place.

I left a reply to a comment in Gerrit but no one but me can see it

Replies to comments on code in Gerrit are first saved as drafts and need to be published via the “Reply” button. This is to prevent multiple emails per review “session” and is similar to the pending review workflow in GitHub. If you see a number next to the “Reply” text in the button, this means you have pending drafts to publish.

If you do not see a large blue “Reply” button near the top of the Gerrit web interface, make sure you are logged in to Gerrit, which requires a Gmail or other Google account.

How does GerritBot determine the final commit message?

The key points to remember:

  • The GitHub PR title and PR description (the first PR comment) are periodically imported into Gerrit in their plaintext form as the Gerrit commit message.
  • To update the Gerrit commit message, you must therefore edit the PR title and PR description using the GitHub web interface.
  • You cannot update the Gerrit commit message just by pushing another commit to the PR with an updated commit message. (Pushing another commit does not automatically update the GitHub PR title or PR description, and hence the updated text won't be imported into Gerrit).

Updating the Gerrit commit messsage via the GitHub PR:

Screenshot of the GitHub PR web interface highlightingthe Edit button in top-right (for editing the Gerrit commit message title) andthe Edit menu option on the first comment (for editing the Gerrit commit messagebody).

In more detail, GerritBot uses the latest PR title and PR description from the GitHub PR to construct the commit message for the Gerrit change. This text is editable via the GitHub web interface (not Gerrit or git):

  • The PR title is editable via the “Edit” button in the top-right of the PR page. This is used for the first line of the commit message in Gerrit.
  • The PR description is in the first text area under the “Conversation” tab of the GitHub PR. It is editable via “Edit” option on the “...” menu. This text is used for the remainder of the commit message body in Gerrit.

Once the PR is edited in GitHub, it can take 10 minutes or so before the Gerrit change is updated.

Note: Gerrit imports the plain text that is viewable as you edit the message in GitHub, and it does not import the rendered text you see in GitHub prior to editing.

One common area of related confusion is around issue references. For example, GerritBot or a human reviewer might ask you to avoid URLs for issue references. In Gerrit, you might see the full URL for an issue, but in the GitHub web interface, you might only see an issue reference like #12345 and it might be unclear where the URL is coming from. This can be due to confusion between the rendered view in GitHub vs. the underlying raw/plain text. If the GitHub web interface shows something like Fixes https://github.com/golang/go/issues/12345 while you are editing the text in GitHub, change it to something like Fixes #12345 or Fixes golang/go#12345 instead. See the Contribution Guide for more on issue references.

What is a CL? What is a Gerrit change?

CL is short for “change list”, which is essentially a patch proposed to be introduced into a repository. The Go project uses Gerrit to carefully review each CL. An example CL is https://go.dev/cl/508475.

Gerrit change is another term for CL.

Can I help review other people's CLs?

Yes, this is highly encouraged, and a great way to familiarize yourself with Gerrit, the Go project's code review process, and the internals of the Go standard library, runtime, compiler, and so on.

You can browse the currently open CLs here and subscribe for updates to interesting CLs by clicking the star icon.

You don't need to be an expert in the code to help with initial review triage. See the section on helping to review CLs in the Gardening wiki page for more details.

I heard Gerrit requires one commit per change. Can I upload multiple commits to my PR?

You can upload as many commits as you like. GerritBot will handle squashing your commits into one change that Gerrit can handle.

Why is GerritBot the owner of my change?

This is due to an open bug with the way Gerrit handles acting as another user. Once that is fixed, the original author will also be the owner of the change.

Can I ask GerritBot to stop posting comments on my PR?

You can toggle comments from GerritBot by using the comments slash command (e.g., /comments off).

Feedback and Bug Reports

Please file an issue and use the x/build/cmd/gerritbot: prefix in the title.

I'd like to add a feature/fix a bug