Schema Change

WARNING: This release contains schema changes. To upgrade:

  java -jar gerrit.war init -d site_path

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

WARNING: The replication plugin now automatically creates missing repositories on the destination if during the replication of a ref the target repository is found to be missing. This is a change in behavior of the replication plugin. To go back to the old behavior, set the parameter remote.NAME.createMissingRepositories in the replication.config file to false.

WARNING: The deprecated approve alias for the review SSH command has been removed. This is important for all users of the Jenkins Gerrit Trigger Plugin since this plugin by default uses the approve command to vote and comment on changes in Gerrit. If you use the Gerrit Trigger Plugin, go to its global configuration in Jenkins and adapt the Gerrit commands to use the review command instead of the approve command.

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 during the site initialization.

Release Highlights

New Features


  • Gerrit is now built with Buck.

  • Documentation is now built with Buck and Asciidoctor.

Gerrit can be configured to use a secondary index with Lucene or Solr.

Existing search operations use the secondary index, when enabled, to increase performance and reduce resource usage.

The following additional search operations are possible when secondary indexing is enabled:

WARNING: After enabling the secondary index, the index must be built using the reindex program before restarting the Gerrit server.


Web UI


  • The change status is shown in a separate column on dashboards and search results.

Change Screens

  • New change screen with completely redesigned UI, using the REST API.

    Users can choose which one to use in their personal preferences, either using the site default or explicitly choosing the old one or new one.

  • Issue 141: In the new change screen, comments can be added on a range of lines.

  • New button to cherry-pick the change to another branch.

  • When issuing a rebase via the Web UI, the committer is now the logged in user, rather than "Gerrit Code Review".

    If the user has more than one email address, the preferred email address will be used.

  • Default user’s full name to git committer name if user has not configured a full name in their profile.

  • Include comment author attributes in comment panels.

    Comment author’s email address and name are included as attributes in comment panels. This makes it easier to filter out CI-based comments using user scripts.

  • Copy reviewed flag to new patch sets for identical files.

    If a user has already seen and reviewed a file, the reviewed flag is forwarded on to the next patch set when the content of the file in the next patch set is identical to the reviewed file.

  • "Uploaded Patch Set 1" change message is added on changes when they are uploaded.


New global capabilities are added.

  • Generate Http Password allows non-administrator users to generate HTTP passwords for users other than themselves.

    This capability would typically be assigned to a non-interactive group to be able to generate HTTP passwords for users from a tool or web service that uses the Gerrit REST API.

  • Run As allows users to impersonate other users by setting the X-Gerrit-RunAs HTTP header on REST API calls.

    Site administrators do not inherit this capability; it must be granted explicitly.


  • The RebasedPatchSet template is removed. Email notifications for rebased changes are now sent with the ReplacePatchSet template.

  • Comment notification emails now include context of comments that are replied to, and links to the file(s) in which comments are made.



  • Plugins may now contribute buttons to various parts of the UI using the UI extension and JavaScript API.

  • Plugins may now provide an About section on their documentation index page.

  • Plugins may now provide separate sections for REST API and servlet documentation on their index page.

  • Plugins may now provide pre-merge validation steps.

  • Plugins may now provide Global capabilities.

  • Plugins may now define their own name and get the name injected at runtime.

  • The "hello world" plugin is replaced with the "cookbook plugin" which has more examples of the plugin API’s usage.

  • Plugins may now trigger and listen to a "project deleted" event.

  • Issue 2101: Plugins implementing LifecycleListener can use auto registration.

  • Plugins may bind REST endpoints with empty view names.

  • Plugins may now provide entries in Gerrit’s top menu.

  • Plugins may now send events to the events stream.

  • Plugins may now bind multiple SSH commands to the same implementation class.

  • Plugins may now provide download schemes and download commands.

    Commonly used download schemes and commands are moved out of core Gerrit and are now implemented by a new core plugin, download-commands.

Commit Message Length Checker

  • Commits whose subject or body length exceeds the limit can be rejected.


  • Automatically create missing repositories on the destination.

    If during the replication of a ref the target repository is found to be missing, the repository is automatically created.

    This is a change in behavior of the replication plugin. To go back to the old behavior, set the parameter remote.NAME.createMissingRepositories in the replication.config file to false.

  • Support for replication of project deletions.

    The replication plugin can now be configured to listen to project deletion events and to replicate the project deletions. By default project deletions are not replicated.

  • Issue 1880: Make {name} placeholder optional when replicating a single project.

    The {$name} placeholder is optional when replicating a single project, allowing a single project to be replicated under a different name.

  • Project names can be matched with wildcard or regex patterns in replication.config.

  • The replication start command does not exit until replication is finished when the --wait option is used.

  • The replication start command displays a summary of the replication status.

  • Retry counts are added to replication task names, so they can be seen in the output of the show-queue command.

  • The remoteNameStyle option can be set to basenameOnly to replicate projects using only the basename on the target server.

  • The startReplication global capability is now provided by the plugin.

  • Pushes to each destination URI are serialized.

    Scheduling a retry to avoid collision with an in-flight push is differentiated from a retry due to a transport error. In the case of collision avoidance, the job is rescheduled according to the replication delay, rather than the retry delay.


  • The commit-msg hook installation command is now configurable.

  • New ls-members command.

  • New set-members command.

    New command to manipulate group membership. Members can be added or removed and groups can be included or excluded in one specific group or number of groups.

  • The full commit message is now included in the data sent by the stream-events command.

  • The show-queue command now shows the time that a task was added to the queue.

  • The deprecated approve alias of the review command is removed.

  • The CHANGEID,PATCHSET format for specifying a patch set in the review command is no longer considered to be a legacy feature that will be removed in future.


  • Add --init option to Daemon to initialize site on daemon start.

    The --init option will also upgrade an already existing site and is processed in non-interactive (batch) mode.

Bug Fixes


  • Use the parent change on the same branch for rebases.

    Since there can be multiple changes with the same commit on different branches, use the parent change on the same branch during rebase.

  • Issue 600: Fix change stuck in SUBMITTED state but actually merged.

  • Issue 1699: Fix handling of projects with trailing ".git" suffix.

  • Limit retrying of submitted changes to 12 hours.

  • Don’t allow project owners to delete branches if force push is blocked.

  • Allow usernames to begin with digit.

  • Verify access to source ref during add branch operation.

    Previously Gerrit didn’t check access to source ref during add branch operation. Because of that users could create a branch from any known commit SHA1, even when they didn’t have access to that commit.

  • Fix Gerrit API sources JAR contents.

    The gerrit-extension-api-X.Y-all-sources.jar did not actually contain any sources.

  • Generate javadoc for Gerrit Extension and Plugin APIs.

  • Issue 2244: Update patch status before skipping duplicate emails.

  • Issue 1640: Catch missing LDAP accounts in group membership.

  • Use rev-parse to find gitdir when generating commit-msg hook hint.

  • Performance Fix: Minimize number of advertisedHaves.

    By filtering the refs before the objectIds are added to advertisedHaves, lots of time can be saved when pushing to complex Gits.


  • Do not persist default project state in project.config.

  • Honor the gerrit.canonicalWebUrl setting when opening the browser after init.

  • Fix query disabled error when Query Limit is set.

  • Honor the gerrit.createChangeId setting from the git config in the commit-msg hook.

  • Issue 2045: Define user scope when parsing server config.

  • Issue 1990: Support optional Certificate Revocation List (CRL) with CLIENT_SSL_CERT_LDAP.

  • Do not override error and gc logging configuration provided by the -Dlog4j.configuration parameter.

  • Fix JdbcSQLException when numbers are read from cache.

Web UI


  • Issue 1574: Correctly highlight matches of text in escaped HTML entities in suggestion results.

  • Issue 1996: The "Keyboard Shortcuts" help popup can be closed by pressing the Escape key.

  • Issue 2013: Correctly populate the list of watched changes when watching more than one project.

  • Display "Working…" when header is hidden.

  • Issue 2125: Correctly shows -1 instead of 1 for label score.

    If a user voted -1, and then another user voted +1 for a label, the label was shown as a red 1 in the change list instead of red -1.

Change Screens

  • Default review comment visibility is changed to expand all recent.

    By default all comments within the last week are expanded, rather than only the most recent.

  • Issue 1814: Sort labels alphabetically by name in the approval table.

  • Don’t add "This patchset was cherry picked to …" for the same change.

    If a patchset is cherry-picked to the same destination branch and ends up on the same change, it does not make sense to add the "This patchset was cherry picked to change …" message.

    In this case, it makes more sense for the message to say "Uploaded patch set N" instead.

  • Make links appear with consistent colors.

  • Prevent duplicate permitted_labels from being shown in labels list.

Diff Screens

  • Issue 1233: Prevent expansion when whole file isn’t loaded.

  • Issue 2122: Show review comments for unchanged files.

    When comparing patch sets and some comment was put in one side, that comment was not shown if there was no code changed between the two patch sets

Project Screens

  • Only enable the delete branch button when branches are selected.

  • Disable the delete branch button while branch deletion requests are still being processed.

User Profile Screens

  • The preferred email address field is shown as empty if the user has no preferred email address.


  • Support raw input also in POST requests.

  • Show granted date for labels/all when using /changes/.

  • Return all revisions when o=ALL_REVISIONS is set on /changes/.


  • The --force-message option is removed from the The review command.

  • Issue 1908: Provide more informative error messages when rejecting updates.

  • Remove the limit in the query of patch sets by revision.

  • Add isDraft in the patchSet attribute of stream-events data.

    This allows consumers of the event stream to determine whether or not the event is related to a draft patch set.

  • Normalize the case of review labels submitted via the The review command.

  • The @CommandMetaData(descr) annotation is deprecated in favor of @CommandMetaData(description).

  • Improve the error message when rejecting upload for review to a read-only project.



  • Better error message when a Javascript plugin cannot be loaded.

  • Plugin documentation links are opened in a new tab.

  • The GitReferenceUpdatedListener.Event API is simplified.

    The Event exposed the getUpdates method which implied that one Event could contain updates of more than one reference. However, this feature was never used.

    The API is simplified in the sense that one Event now corresponds to one ref update only.

  • Make plugin servlet’s context path authorization aware.

Review Notes

  • Do not try to create review notes for ref deletion events.

  • Fix committing the notes from the export command.

  • Issue 2087: Fix note creation when the same commit exists in another Git repository.

  • Improve the export command performance.

  • Create review note also when newObjectId already present in another branch.

  • Correct documentation of the export command.


  • Email notifications are sent for new changes created via actions in the Web UI such as cherry-picking or reverting a change.


  • return non-zero on errors



  • Update JGit to

  • Update gwtorm to 1.7

  • Update guice to 4.0-beta

  • Update guava to 15.0

  • Update H2 to 1.3.173

  • Update bouncycastle to 1.44

  • Update Apache Mina to 2.0.7

  • Issue 2232: Update Apache SSHD to

  • asciidoctor 0.1.4 is now required to build the documentation

  • jsr305 library was removed

  • Issue 2232: Update Jsch to 1.5.0