Gerrit 2.9 is now available:

WARNING: Support for Java 1.6 has been discontinued. As of Gerrit 2.9, Java 1.7 is required.

Gerrit 2.9 includes the bug fixes done with Gerrit 2.8.1, Gerrit 2.8.2, Gerrit 2.8.3, Gerrit 2.8.4, Gerrit 2.8.5, Gerrit 2.8.6 and Gerrit These bug fixes are not listed in these release notes.

Important Notes

WARNING: This release contains schema changes. To upgrade:

  java -jar gerrit.war init -d site_path
  java -jar gerrit.war reindex --recheck-mergeable -d site_path

WARNING: Upgrading to 2.9.x requires the server be first upgraded to 2.1.7 (or a later 2.1.x version), and then to 2.9.x. If you are upgrading from 2.2.x.x or later, you may ignore this warning and upgrade directly to 2.9.x.

WARNING: When upgrading from version 2.8.4 or older with a site that uses Bouncy Castle Crypto, new versions of the libraries will be downloaded. The old libraries should be manually removed from site’s lib folder to prevent the startup failure described in Issue 3084.

WARNING: Support for query via the SQL index is removed. The usage of a secondary index is now mandatory.

WARNING: The sortkey and sortkey_prev options on the query changes REST endpoint are deprecated.

WARNING: The new change screen only displays download commands if the download-commands core plugin or any other plugin providing download commands is installed. The download-commands plugin provides the standard download schemes and commands. It is packaged together with Gerrit and can be installed, or upgraded, during the site initialization:

Installing the plugin for the first time
  • Batch init:

    By default the batch init does not install any core plugin. To install the download-commands plugin during batch init, specify the --install-plugin download-commands option:

      $ java -jar gerrit-2.9.war init -d site --batch --install-plugin download-commands
  • Interactive init:

    There is a question whether the download-commands plugin should be installed. To install the plugin the question must be answered with y:

      Install plugin download-commands version v2.9 [y/N]? y
Upgrading the plugin

Pay attention that the download-commands plugin from Gerrit 2.8 is not compatible with Gerrit 2.9 and must be upgraded:

  • Batch init:

    With the batch init it is not possible to upgrade core plugins.

  • Interactive init:

    The interactive init asks whether the plugin should be upgraded:

      Install plugin download-commands version v2.9 [y/N]? y
      version v2.8.6.1 is already installed, overwrite it [y/N]? y
  • Manual upgrade:

    The plugin can be upgraded manually by copying the new plugin jar into the site’s plugins folder.

Release Highlights

  • Issue 2065: The new change screen is now the default change screen.

    The documentation of the new review UI describes the new screens in detail and highlights the important functionality with screenshots.

    Users that are accessing the new change screen for the first time are informed about the new change screen by a welcome popup. The welcome popup links to the review UI documentation and allows users to go back to the old change screen.

New Features

Web UI


  • Project links by default link to the project dashboard.

New Change Screen

  • The new change screen is now the default change screen.

  • The layout was changed so that the focus is now on the commit message, the change ID and the change status.

  • Draft comments are displayed in the reply box.

    There are links to navigate to the inline comments which can be used if a comment needs to be edited.

  • New inline comments from other users, that were published after the current user last reviewed this change, are highlighted in bold.

  • New summary comments from other users, that were published after the current user last reviewed this change, are automatically expanded in the change history.

    The support for the old comment visibility strategy is discontinued.

  • Issue 93: Inline comments are shown in the change history.

  • Issue 592: A reply icon is shown on each change message.

  • Quoting is possible when replying to a comment.

  • Issue 2313: Show whether a related change is merged or old.

  • New Related Changes tabs:

    • Cherry-Picks

    • Same Topic

    • Conflicts With

  • The title of the Patch Sets drop-down panel shows the number of the currently viewed patch set and the total number of patch sets, in the form: "current patch set/number of patch sets".

  • The currently viewed patch set is displayed in the Patch Sets title.

  • Keyboard shortcuts to navigate to next/previous patch set.

  • Support [, / and ] keys to navigate between files in a cycle.

  • Issue 2078: Show a tooltip on reviewers indicating on which labels they can vote.

  • The Submit button is enabled even if the change is not mergeable.

    This allows to do the conflict resolution for a change series in a single merge commit and submit the changes in reverse order.

  • New Open All button in files header.

  • If a merge commit is viewed this is highlighted by an icon. In this case the parent commits are also shown.

  • Issue 2191: New copy-to-clipboard button for commit ID.

New Side-by-Side Diff Screen

  • Issue 348: The lines of a patch file are linkable.

    These links can be used to directly link to certain inline comments.

  • Issue 2395: The line length preference is used to draw a margin line at that many columns of text.

    This allows a user to configure their preferred width (e.g. 80 columns or 100 columns) and see the margin, making it easier to identify lines that run over that width.

  • Issue 2530: All diff preferences are honored.

  • Issue 148: The full file path is shown.

Change List / Dashboards

  • The Status column shows Merge Conflict for changes that are not mergeable.

  • A new Size column shows the change size as a colored bar.

    • The user preference Show Change Sizes As Colored Bars In Changes Table can be disabled to get the size information displayed as text.

    • The number of changed lines by which a change is considered as a large change can be configured.

  • Support to drill down into dashboard section.

    Clicking on the section title executes the query of this section without the limit operator.

Project Screens

  • The general project screen provides a copyable clone command that automatically installs the commit-msg hook.

  • Issue 562: Project owners can change HEAD from the project branches screen.

  • Issue 1298: Administrators can change the parent project from the project access screen; other users can save changes to the parent project for review and get the change approved by an administrator.

  • The project list displays icons for projects that are read only or hidden.

  • The Git garbage collection can be triggered from the general project screen if the user has the Run Garbage Collection global capability.

User Preferences

  • Users can choose the UK date format to render dates and timestamps in the UI.

Secondary Index

  • Support for query via the SQL index is removed. The usage of a secondary index is now mandatory.

  • New --recheck-mergeable option on the reindex program.


  • New --notify option on the review command allowing to control when email notifications should be sent.

  • Issue 1752: New --branch option on the review command.

  • New --all-reviewers option on the query command allowing query results to include information about all reviewers added on the change.

  • New apropos command to search the Gerrit documentation.

  • Issue 1156: New create-branch command.



  • Results returned by the query changes endpoint are now paginated using offsets instead of sortkeys.

    The sortkey and sortkey_prev parameters on the endpoint are deprecated. The results are now paginated using the --limit (-n) option to limit the number of results, and the -S option to set the start point.

    Queries with sortkeys are still supported against old index versions, to enable online reindexing while clients have an older JS version.


Access Rights

  • New global capability for viewing all accounts.

  • New global capability for viewing the list of installed plugins.

  • Issue 1993: New Change Owner group that allows to assign label permissions to the change owner.

  • Support on behalf of for submit.

  • Allow service users to access REST API if auth.gitBasicAuth = true.

    If auth.gitBasicAuth is set to true in the gerrit.config file all HTTP traffic is authenticated using standard BasicAuth and the credentials are validated using the same auth method as configured for the Gerrit Web UI. E.g. for LDAP this means that users must use their LDAP password for Git over HTTP and for accessing the REST API.

    Service users are technical users that were created by the create-account SSH command. These users only exist in Gerrit and hence they do not have any LDAP password. This is why service users were not able to make use of the REST API if auth.gitBasicAuth was set to true.

    Now if auth.gitBasicAuth is set to true users that exist only in Gerrit but not in LDAP are authenticated with their HTTP password from the Gerrit database.

  • New is:mergeable search operator.

    Finds changes that have no merge conflicts and can be merged into the destination branch.

  • Issue 2163: New parentproject search operator.

    Finds changes in the specified project or in one of its child projects.

  • Issue 2162: New conflicts search operator.

    Finds changes that conflict with the specified change.

  • New operators for absolute last-updated-on search.

  • Support exact match on file parts in file operator.

  • Query shortcuts

    • o = owner

    • r = reviewer

    • p = project

    • f = file


  • Gerrit Inspector: interactive Jython shell.

    New -s option is added to the Daemon to start an interactive Jython shell for inspection and troubleshooting of live data of the Gerrit instance.




  • The removal of reviewers and their votes is recorded as a change message.

  • Issue 2229: The change URL is returned on push if the change is updated.

  • The topic is included into merge commit messages if all merged changes have the same topic.

  • Stable CSS class names.


JavaScript Plugins

  • JavaScript Callbacks

    • Gerrit.on('history\', f)

    • Gerrit.on('submitchange\', f)

    • Gerrit.on('showchange\', f)

  • change_plugins element on the new change screen that allows to insert arbitrary HTML fragments from plugins.

Bug Fixes

Access Rights

  • Fix possibility to overcome BLOCK permissions.

Web UI

  • Issue 2652: Copy label approvals when cherry-picking change to same branch.

  • Issue 2662: Limit file list in new change screen to files that were touched in new patch set.

  • Issue 2308: Show related changes in new change screen for merged changes if there are open descendants.

  • Issue 2635: Fix copying of download commands by Cmd-C in Safari.

  • Issue 2178: Fix background of reply box on new change screen getting transparent.

  • Issue 2362: Show quick approve button only for current patch set.

  • Issue 2405: Update Patch Sets drop-down panel when draft patch set is deleted.

  • Issue 2397: Fix linkifying of topics that are set to a URL.

  • Issue 2151: Fix overflowing of long lines in commit message block.

  • Issue 2401: Fix truncated long lines in new side-by-side diff screen.

  • Issue 2225: Display larger icons for Prev / Next and Up to Change links on new side-by-side diff screen.

  • Issue 2340: Fix selection in new side-by-side diff screen.

  • Issue 2409: Show in new side-by-side diff screen updates of submodule links.

  • Issue 2481: After showing a binary file in the unified diff screen switch back to the side-by-side diff screen when the user navigates to the next/previous file.

  • Issue 2417: Respect base diff revision for files REST call.

  • Issue 2654: Require the user to confirm setting the username.

    Once the username has been set, it cannot be edited. This can cause problems for users who accidentally set the wrong username. A confirmation dialog now warns the user that setting the username is permanent and the username is only set when the user confirms.

  • Issue 2635: Fix copying from copyable label in Safari.

Secondary Index

  • Fix Online Reindexing.

  • Fix for full-text search with Lucene.

    The full-text search was using a fuzzy query which used the edit distance to find terms in the index close to the provided search term. This produced bizarre results for queries like "message:1234".

    Instead, use Lucene’s QueryBuilder with an analyzer to convert a full-text search word/phrase into a phrase query.

  • Issue 2281: Reindex change after updating commit message.


  • Issue 2568: Update description file during PUT /projects/{name}/config.


  • Issue 2516: Fix parsing of label name on review command.

  • Issue 2440: Clarify for review command when --verified can be used.


  • Issue 2551: Handle absolute URLs in the top level menu.

  • Issue 2391: Respect servlet context path in URL for top menu items.


  • Issue 2382: Clean left over data migration after removal of TrackingIds table.


  • Update JGit to

    This upgrade fixes the MissingObjectExceptions in Gerrit that are described in issue 2025.

  • Update gwtjsonrpc to 1.5

  • Update gwtorm to 1.13

  • Update guava to 16.0

  • Update H2 to 1.3.174

    This version includes a fix for an LOB deadlock between reading and updating LOB columns. This could lead to a deadlock between web and SSH clients as described in issue 2365.

  • Update Jetty to 9.1.0.v20131115

  • Update Servlet API to 3.1

  • Update Lucene to 4.6.0

  • Update GWT to 2.6.0



  • Default push refSpec is changed to refs/*:refs/* (non-forced push).

    The default push refSpec for the replication plugin has changed from forced to non-forced push (was +refs/*:refs/* and now is refs/*:refs/*). This change should not impact typical replication topologies where the slaves are read-only and can be pushed by their masters only. If you wanted explicitly to overwrite all changes on the slaves, you need to add a push=+refs/*:refs/* configuration entry for each replication target.

  • Support replication of HEAD updates.

  • Stream events for ref replication.

  • Replications failed due to "failed to lock" errors are retried.

  • Configuration changes can be detected and replication is automatically restarted.

Issue Tracker System plugins

WARNING: The hooks-* plugins (plugins/hooks-bugzilla, plugins/hooks-jira and plugins/hooks-rtc) are deprecated with Gerrit 2.9.

There are new plugins for the integration with Bugzilla, Jira and IBM Rational Team Concert:

The new issue tracker system plugins have a common base which is plugins/its-base.

The configuration of the new plugins is slightly different than the configuration of the old plugins because they use different section names in the Gerrit configuration. For easy migration the new plugins have an init step that allows to take over the configuration from the old plugins during the Gerrit initialization phase.

New Features:

  • The issue tracker integration can be enabled/disabled per project.

  • Parent projects can enforce the issue tracker integration for their child projects.

  • It can be configured for which branches of a project the issue tracker integration is enabled.

  • Whether the issue tracker integration is enabled/disabled for a project can be changed from the ProjectInfoScreen in the Gerrit WebUI.