Gerrit Code Review - System Design

Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system.

Gerrit makes reviews easier by showing changes in a side-by-side display, and allowing inline/file comments to be added by any reviewer.

Gerrit simplifies Git based project maintainership by permitting any authorized user to submit changes to the master Git repository, rather than requiring all approved changes to be merged in by hand by the project maintainer. This functionality enables a more centralized usage of Git.

Git is a distributed version control system, wherein each repository is assumed to be owned/maintained by a single user. There are no inherent security controls built into Git, so the ability to read from or write to a repository is controlled entirely by the host’s filesystem or network access controls.

The objective of Gerrit is to facilitate Git development by larger teams: it provides a means to enforce organizational policies around code submissions, eg. "all code must be reviewed by another developer", "all code shall pass tests". It achieves this by

Developers create one or more changes on their local desktop system, then upload them for review to Gerrit using the standard git push command line program, or any GUI which can invoke git push on behalf of the user. Authentication and data transfer are handled through SSH and HTTPS. Uploads are protected by the authentication, confidentiality and integrity offered by the transport (SSH, HTTPS).

Each Git commit created on the client desktop system is converted into a unique change record which can be reviewed independently.

A summary of each newly uploaded change is automatically emailed to reviewers, so they receive a direct hyperlink to review the change on the web. Reviewer email addresses can be specified on the git push command line, but typically reviewers are added in the web interface.

Reviewers use the web interface to read the side-by-side or unified diff of a change, and insert draft inline/file comments where appropriate. A draft comment is visible only to the reviewer, until they publish those comments. Published comments are automatically emailed to the change author by Gerrit, and are CC’d to all other reviewers who have already commented on the change.

Reviewers can score the change ("vote"), indicating whether they feel the change is ready for inclusion in the project, needs more work, or should be rejected outright. These scores provide direct feedback to Gerrit’s change submit function.

After a change has been scored positively by reviewers, Gerrit enables a submit button on the web interface. Authorized users can push the submit button to have the change enter the project repository. The user pressing the submit button does not need to be the author of the change.

End-user web browsers make HTTP requests directly to Gerrit’s HTTP server. As nearly all of the Gerrit user interface is implemented in a JavaScript based web app, the majority of these requests are transmitting compressed JSON payloads, with all HTML being generated within the browser.

Gerrit’s HTTP server side component is implemented as a standard Java servlet, and thus runs within any J2EE servlet container. The standard install will run inside Jetty, which is included in the binary.

End-user uploads are performed over SSH or HTTP, so Gerrit’s servlets also start up a background thread to receive SSH connections through an independent SSH port. SSH clients communicate directly with this port, bypassing the HTTP server used by browsers.

User authentication is handled by identity realms. Gerrit supports the following types of authentication:

Permissions are specified on branch names, and given to groups. For example,

this provides a rule, granting Release-Engineers push permission for stable branches.

There are fundamentally two types of permissions:

Read permissions need special treatment across Gerrit, because Gerrit should only surface data (including repository existence) if a user has read permission. This means that

Metadata (eg. OAuth credentials) is also stored in Git. Existing endpoints must refuse creating branches or changes that expose these metadata or allow changes to them.

Gerrit has a plug-in architecture. Plugins can be installed by dropping them into $site_directory/plugins, or at runtime through plugin SSH commands, or the plugin REST API.

As a source code review system for open source projects, where the commonly preferred language for communication is typically English, Gerrit does not make internationalization or localization a priority.

The majority of Gerrit’s users will be writing change descriptions and comments in English, and therefore an English user interface is usable by the target user base.

Whenever possible Gerrit displays raw text rather than image icons, so screen readers should still be able to provide useful information to blind persons accessing Gerrit sites.

Standard HTML hyperlinks are used rather than HTML div or span tags with click listeners. This provides two benefits to the end-user. The first benefit is that screen readers are optimized to locating standard hyperlink anchors and presenting them to the end-user as a navigation action. The second benefit is that users can use the 'open in new tab/window' feature of their browser whenever they choose.

When possible, Gerrit uses the ARIA properties on DOM widgets to provide hints to screen readers.

Gerrit requires a JavaScript enabled browser.

As Gerrit is a pure JavaScript application on the client side, with no server side rendering fallbacks, the browser must support modern JavaScript semantics in order to access the Gerrit web application. Dumb clients such as lynx, wget, curl, or even many search engine spiders are not able to access Gerrit content.

All of the content stored within Gerrit is also available through other means, such as gitweb or the git:// protocol. Any existing search engine crawlers can index the server-side HTML served by a code browser, and thus can index the majority of the changes which might appear in Gerrit. Therefore the lack of support for most search engine crawlers is a non-issue for most Gerrit deployments.

Gerrit optionally surfaces links to HTML pages in a code browser. The links are configurable, and Gerrit comes with a built-in code browser, called Gitiles.

Gerrit integrates with some types of corporate single-sign-on (SSO) solutions, typically by having the SSO authentication be performed in a reverse proxy web server and then blindly trusting that all incoming connections have been authenticated by that reverse proxy. When configured to use this form of authentication, Gerrit does not integrate with OpenID providers.

When installing Gerrit, administrators may optionally include an HTML header or footer snippet which may include user tracking code, such as that used by Google Analytics. This is a per-instance configuration that must be done by hand, and is not supported out of the box. Other site trackers instead of Google Analytics can be used, as the administrator can supply any HTML/JavaScript they choose.

Gerrit does not integrate with any Google service, or any other services other than those listed above.

Plugins (see above) can be used to drive product integrations from the Gerrit side. Products that support Gerrit explicitly can use the REST API or the SSH API to contact Gerrit.

Gerrit stores the following information per user account:

The full name and preferred email address fields are shown to any site visitor viewing a page containing a change uploaded by the account owner, or containing a published comment written by the account owner.

Showing the full name and preferred email is approximately the same risk as the From header of an email posted to a public mailing list that maintains archives, and Gerrit treats these fields in much the same way that a mailing list archive might handle them. Users who don’t want to expose this information should either not participate in a Gerrit based online community, or open a new email address dedicated for this use.

As the Gerrit UI data is only available through XSRF protected JSON-RPC calls, "screen-scraping" for email addresses is difficult, but not impossible. It is unlikely a spammer will go through the effort required to code a custom scraping application necessary to cull email addresses from published Gerrit comments. In most cases these same addresses would be more easily obtained from the project’s mailing list archives.

The user’s name and email address is stored unencrypted in the All-Users repository.

There is no spam protection for the Git protocol upload path. Uploading a change successfully requires a pre-existing account, and a lot of up-front effort.

Gerrit makes no attempt to detect spam changes or comments in the web UI. To post and publish a comment a client must sign in and then use the XSRF protected JSON-RPC interface to publish the draft on an existing change record.

Absence of SPAM handling is based upon the idea that Gerrit caters to a niche audience, and will therefore be unattractive to spammers. In addition, it is not a factor for corporate, on-premise deployments.

Gerrit supports the Git wire protocol, and an API (one API for HTTP, and one for SSH).

The git wire protocol does a client/server negotiation to avoid sending too much data. This negotiation occupies a CPU, so the number of concurrent push/fetch operations should be capped by the number of CPUs.

Clients on slow network connections may be network bound rather than server side CPU bound, in which case a core may be effectively shared with another user. Possible core sharing due to network bottlenecks generally holds true for network connections running below 10 MiB/sec.

Deployments for large, distributed companies can replicate Git data to read-only replicas to offload fetch traffic. The read-only replicas should also serve this data using Gerrit to ensure that permissions are obeyed.

The API serves requests of varying costs. Requests that originate in the UI can block productivity, so care has been taken to optimize these for latency, using the following techniques:

Git does not impose fundamental limits (eg. number of files per change) on data. To ensure stability, Gerrit configures a number of default limits for these.

Gerrit is structured as a single JVM process, reading and writing to a single file system. If there are hardware failures in the machine running the JVM, or the storage holding the repositories, there is no recourse; on failure, errors will be returned to the client.

Deployments needing more stringent uptime guarantees can use replication/multi-master setup, which ensures availability and geographical distribution, at the cost of slower write actions.

Gerrit stores Apache style HTTPD logs, as well as ERROR/INFO messages from the Java logger, under $site_dir/logs/.

Published comments contain a publication date, so users can judge when the comment was posted and decide if it was "recent" or not. Only the timestamp is stored in the database, the IP address of the comment author is not stored.

Changes uploaded over the SSH daemon from git push have the standard Git reflog updated with the date and time that the upload occurred, and the Gerrit account identity of who did the upload. Changes submitted and merged into a branch also update the Git reflog. These logs are available only to the Gerrit site administrator, and they are not replicated through the automatic replication noted earlier. These logs are primarily recorded for an "oh s**t" moment where the administrator has to rewind data. In most installations they are a waste of disk space. Future versions of JGit may allow disabling these logs, and Gerrit may take advantage of that feature to stop writing these logs.

A web server positioned in front of Gerrit (such as a reverse proxy) or the hosting servlet container may record access logs, and these logs may be mined for usage information. This is outside of the scope of Gerrit.

Part of Gerrit Code Review