New change workflows for changes not yet ready for full review (formerly Drafts).
The new PolyGerrit UI is mature enough for most uses.
Account data is stored in NoteDb.
NoteDb for change metadata is considered stable, and new sites use it by default.
NoteDb migration for change metadata is available.
Made several improvements and additions to the documentation to help users find the information they need.
This release contains schema changes. To upgrade:
java -jar gerrit.war init -d site_path
Support for draft changes removed
Support for draft changes and draft patch sets has been completely removed.
In most cases, the new Work-In-Progress workflow is a suitable replacement. Note that in the Draft workflow, an individual patch set can be a Draft. However, in both the new Work-In-Progress and Private workflows, WIP and Private apply to the whole change, not an individual patch set.
When upgrading from an earlier version, draft changes are migrated. This applies to all draft changes, or changes with draft patch sets (even if the highest patch set is not a draft), as follows:
- The “Draft” flag is removed from all patch sets.
- If the change has been merged or abandoned, no further action is taken.
- Otherwise, the change is moved to one of
- Work-In-Progress change (this is the default)
- Private change
The upgrade process prompts (once) for what Drafts should be migrated to; either WIP (default) or Private.
The migration means that some draft patch sets, which were previously hidden, might now be visible to some users who could not previously view them.
Change owners can make them private again using the “Mark Private” option in the UI, or using the REST API.
Votes no longer changed retroactively due to permissions
Historically, Gerrit would retroactively change votes on a label when permissions for the voting user changed. For example, if a user voted Code-Review+2, but then later lost permission to vote +2 (for example, was removed from a Maintainers group), all CR+2 votes by that user on open changes would suddenly appear as CR+1. In 2.15, this retroactive behavior no longer applies: the CR+2 votes remain CR+2, even if permissions were changed.
This new behavior makes label permissions more consistent with other permissions: usually, permission changes don’t apply retroactively (you can’t un-submit a change), and the permission is only checked at the time an action is performed. It also fixes some technical issues and improves performance of reindexing changes.
Starting in the 2.14.x bugfix series, all release JARs and documentations are signed by the Gerrit maintainers. This policy will continue for all future releases.
New URL Scheme
By default, all Gerrit URLs generated and used by the UI include not just the change number but the project name as well.
In addition to providing more context to humans reading the URL, this new scheme improves performance under NoteDb, and paves the way for load balancing a multi-master installation with repository affinity.
Old URLs will continue to be supported, and simply redirect to the new URLs.
NoteDb for Accounts
Almost all account data is now stored in
The account data is migrated automatically during the upgrade process by running
The only account data not stored in NoteDb proper are the groups (remain in ReviewDb) and the reviewed flags which were moved to an external database (AccountPatchReviewDb) since 2.13.
For Gerrit slaves the branches that contain the account data must be replicated.
NoteDb for Changes
With this release, the new Gerrit storage backend, NoteDb, is officially supported for storing change metadata and is the default storage backend for new installations.
For existing sites, migration to the new backend may be done either offline or online in a running server.
Support for ReviewDb will be removed in Gerrit 3.0. Gerrit 3.0 will only support offline migration; to run an online migration, you must use the 2.15.x series.
Daemon User Setup
The setup documentation now recommends setting up a user named
gerrit2. This username can be anything; the choice of name doesn’t affect
any functionality. However, some example commands in the documentation may
refer to the new
gerrit user, so admins might need to tweak them to refer to
Strict validation on labels
In 2.15, posting a review including a vote on any labels that does not exist or is outside of the permitted range based on the ACLs will now always result in a failure of the entire operation. Previously, if the “strict labels” option was set to disabled in the review input, votes to any invalid labels would be silently ignored. This option has now been removed from the REST API’s ReviewInput as well as the SSH review command.
CI systems that rely on the non-strict behaviour of earlier Gerrit versions may require additional configuration to avoid casting votes to labels which are invalid for the change.
Following feedback on the 2.15 release
a new configuration option
change.strictLabels was introduced in 2.15.2
to allow the new strict functionality to be optionally enabled. By default it is
disabled to maintain backwards compatibility with previous release.
Java runtime version requirement
Gerrit requires Java Runtime Environment (JRE) version 8; it is not compatible with JRE 9 or newer yet. For more information, see Issue 7843.
Implement admin interface (projects, groups and plugins).
Refreshed UI based on material design.
Add hashtag support.
Add support to show uploader on change screen.
Lots of bug fixes.
Draft, Private, Work-In-Progress
The draft change feature has been removed, and replaced with two separate features:
- Private changes are visible only to the owner and reviewers.
- Work-in-progress changes do not generate notifications.
Ignore Changes, Mark Reviewed
Changes can be ignored, or marked as reviewed, to reduce email notifications and keep dashboards cleaner.
Explicitly Record Reverted Changes
When a change is reverted via the “Revert” button, this fact is recorded in the
change metadata of the newly-created revert change, not just in the commit
message as in the past. A new search operator
revertof: allows for searching
for reverts of a given change.
Delete Inline Comments
Individual inline comments can be deleted after the fact by site administrators.
CCs Users By Email
Users may be CCed on changes by entering their email address, even if they have not registered an account on the Gerrit server.
This feature is only available when using NoteDb.
Publish Comments on Push
When pushing new patch sets on a change or a series of changes, users can configure Gerrit to automatically publish any pending draft comments they have on those changes, avoiding the need to click through the web UI to publish all comments.
Mark Changes Due to Rebase
When diffing two patch sets of the same change that have different parents, some differences between the patch sets may be due to the rebase, instead of changes between the patch set and its base. These differences are now highlighted in the UI (PolyGerrit only), and are not counted towards the size of diffs.
Improved Push Error Messages
When a push fails because the user does not have the required permission, the generic message
(prohibited by Gerrit) has been replaced with a detailed message describing
the exact permissions required.
With this release, we have updated several sections of the documentation to make it easier for users to find the information they need. These updates include:
- New Quickstart guide to install Gerrit on Linux
- New About Gerrit section that helps to introduce users to Gerrit
- New Concepts section to explain Gerrit-specific concepts.
We have also made changes to improve navigation throughout the documentation.
- ProjectInfo now contains label configuration information.
ChangeInfo now records the change that this change was a revert of.
ChangeInfo now contains the submitter, for merged changes.
ReviewInput no longer offers the
strict_labelsoption. It will behave as enabled with earlier versions of Gerrit. The entire operation will now fail if any of the labels used are not within the user’s permitted range based on ACLs or if the label is not configured for the project/branch.
now contains a
New Java API for accessing plugins.
New Java API for accessing custom project dashboards.
getGroupsmethod in account API to get a user’s group memberships.
ChangeReportFormatterextension point for customizing the report output from
Instances of IdString used to return true when
equalswas given a String instance equal to the IdString’s URL-encoded value. This violates symmetry, so this behavior was removed: IdStrings now never compare equal to Strings.
It is now possible to replicate directly to another Gerrit instance.
Is is possible to enable replication to different Gerrit instance by using
gerrit+ssh://as the protocol name followed by the hostname of another Gerrit server.
Username parameters are added to hook invocations.
When an account parameter is passed to a hook, it gets formatted as
Name (Email)or just
Namewhen the account does not have an email address. If the account’s name is not set, the name is “Anonymous Coward”. From this information it is not easy for a hook to get the account’s username.
All hooks that take an account parameter now automatically also get a corresponding username parameter. For example if the hooks takes the parameter
--change-owner Name (Email)it will automatically also get the parameter
Update Apache Commons Codec to 1.10
Update Apache Commons Compress to 1.13
Update Apache Commons Validator to 1.6
Update Apache Mina SSHD to 1.6.0
Update AutoValue to 1.4.1 (updated to 1.6.2 in 2.15.4)
Update Blame Cache to 0.2-5
Update Bouncy Castle to 1.57
Update Dropwizard to 3.2.4
Update Gitiles Blame to 0.2-4
Update GWT to 2.8.1
Update Jetty to 9.3.18.v20170406
Update JGit to 126.96.36.199710071750-r
Update Joda-Time to 2.9.9
Update juniversalchardet to 2.0.0
Update Lucene to 5.5.4
Update Pegdown to 1.6.0
Update Polymer to 1.11.0
Update Soy to 2017-04-23
Update JGit to 188.8.131.52810051924-r to fix CVE-2018-17456.
This release of JGit implements validation of
.gitmodulesfiles to protect unguarded tools against CVE-2018-17456.
Issue 9823: Fix force push permission check for administrators and project owners over SSH.
It was possible for an administrator or project owner to force push to a project over SSH without having the Force Push permission.
This issue did not affect regular users, or pushes over HTTP.
Update jackson-core to 2.9.7.
There have been several releases since 2.6.6 including many bug fixes and security fixes.
Update elasticsearch-rest-client to 6.4.2.
Issue 9705: Fix blank dropdown for ‘Only serve as parent for other repositories’ option when creating a new repository.
Issue 9610: Add support for showing the ‘effective’ value of the max object size limit setting.
Issue 9787: Fix permission check for toggling WIP flag when posting review.
Issue 9655: Fix support for setting owner of group to a single user.
Issue 7053: Modify search autocompletion to include only email.
Issue 8859: Skip plugin capability check for administrators.
Issue 9642: Fix rendering of ‘Ready’ and ‘Start Review’ buttons.
Issue 8472: Count unresolved message threads within thread groups rather than by leaves.
Issue 8202: Add current patch set to
Issue 9483: Perform fonts preloads in “anonymous” cross-origin mode.
Issue 8582: Turn off autoReindexIfStale by default.
Issue 7750: Fix enforcing of signed push when ‘Require signed push’ is enabled.
Remove unused font files.
- Issue 9670: Add support for Elasticsearch 6.4.0.
Issue 9711: Add a change deleted event.
Since 2.14 it is possible to delete changes, however there was no specific event emitted. A new change deleted event is added, which is notified to
stream-eventsclients. The hooks plugin is updated to support a
Issue 9689: Fix visibility of tag creation form on the project screen (GWT).
The tag creation form was shown when the user had “Create Reference” permission on
It is possible to set the limit per project in the
refs/meta/config, and at global level in
$site/etc/gerrit.config. The project setting may override the global setting if it is lower. Changing the global setting requires a server restart.
A limitation of this implementation is that we cannot set the limit at a project level and have it inherited to its child projects; it is necessary to explicitly set the limit on each child project.
A new global option
receive.inheritProjectMaxObjectSizeLimitis added, and when this is enabled the project-level setting is inherited from the parent. This new setting is disabled by default to keep backwards compatibility with the original behavior.
Allow more email RFC characters in the username.
It was possible to set a username with an email-address-like string, but only as far as the fact that the
@character was allowed. Most of the other characters allowed by the RFC were not allowed.
Ensure user authentication in
The order of filters made request authentication only work when the HTTP request was issued from the Gerrit UI, but not work when REST API was used.
commit-message-length-validation plugin: Use “warning” prefix to allow colorization of remote output.
From version 2.19 of git, the “warning” keyword will be highlighted in the remote output when
color.remoteis enabled in the git config.
- Fix display of “Delete Changes” permission in access screen on GWT UI.
- Fix permission check when deleting a single branch with the “Delete Branches” REST endpoint.
- Include cause in exception when failing to save config in the “Set Config” REST endpoint.
- Issue 9482: Fix staleness checker for URL-encoded project names.
Validate connections when sending a request to the database.
In some cases it was possible to attempt to reuse an already closed connection, which resulted in an internal server exception.
- Issue 9586 Reload change page to land on the latest patch set after change submission in PolyGerrit.
Upgrade JGit to 184.108.40.206809180939-r.
- Issue 9153: Fix querying for filenames with special characters.
Issue 9667: Fix handling of output stream in LFS server.
Fix errors during cleanup after deleting refs.
Fix errors during cleanup after running garbage collection.
Fix atomic lock file creation on NFS.
Users should note that for repositories with a high number of references (for example in excess of 300K refs) and in a server with high traffic, this solution may not scale well and should be tested carefully.
Upgrade guice to 4.2.0.
Guice version 4.2.0 includes performance improvements.
- Upgrade elasticsearch-rest-client to 6.4.1.
- Upgrade Dropwizard Metrics to 4.0.3.
- Upgrade auto-value to 1.6.2.
- Upgrade PostgreSQL connector to 42.2.4.
- Upgrade MariaDB connector to 2.3.0.
- Issue 8915: Fix file handle leak when running GC. Upgrade JGit to 220.127.116.11712150930-r.15-g5fe8e31d4 which includes a fix to prevent the file handle leak.
- Issue 8866: Add project and account settings to create new changes as WIP by default.
- Issue 6094 and Issue 9112: Add support for Elasticsearch versions 5 and 6. Support is added for Elasticsearch versions 5.6 (tested with versions 5.6.9 and 5.6.10), 6.2 (tested with version 6.2.4) and 6.3.1. Version 2.4 is still supported (tested with version 2.4.6). Instead of using the ‘Jest’ client to communicate with Elasticsearch, the Elasticsearch low level API is now used. Support for Elasticsearch is still considered experimental, and is not recommended for production use.
- Issue 9372:
Simplify the configuration of Elasticsearch servers.
Instead of specifying each server in a separate
[elasticsearch "name"]section, with separate values
port, the servers are now configured as a list of
servervalues in the
[elasticsearch]section. This also fixes Issue 9383 where a “default” server
http://localhost:9200would be added by the site initialization even if other servers were already explicitly configured. During startup the list of configured Elasticsearch servers is logged at info level.
- Issue 9146 and Issue 9147: Fix Elasticsearch queries for results with substrings in keywords. Doing a query that involved the characters “.” and “_” from full text fields did not include results with keywords as a substring. This behavior was different from Lucene, where these two characters are mapped to the space character (“ “) so that the query returns keywords separated by them.
- Allow to omit the
elasticsearch.passwordis specified, the
usernamecan be omitted and it will default to
elasticwhich is the default username configured when running Elasticsearch with security enabled.
- Allow to assign “Delete Own Changes” permission to “Change Owners”. It was only possible for a user to delete their own change if they were a member of a group that was assigned the “Delete Own Changes” permission. This was counter-intiuitive as it was necessary to either create a specific group, or assign the permission to “Registered Users”. It is now possible to assign this permission to the “Change Owners” virtual group.
- Issue 9354: Add “Delete Changes” permission. It was only possible for a user to delete another user’s change if they were a member of a group that was assigned the “Administrate Server” permission. A new “Delete Changes” permission is added. This permission can be assigned to a group, or to the “Project Owners” virtual group.
- Issue 9345:
Fix creation of plugin log file when
log4j.configurationis set When the environment variable
log4j.configurationis set, log files defined by plugins were not created because the appender couldn’t be found.
- Fix repeated
Change-Idin error message when
Change-Idline is not in the footer.
- Issue 9245: Return the correct information in JSON response after moving a change. When moving a change by the REST API, the JSON response contained the branch name of the original destination rather than the new destination.
- Fix internal error when moving a change to a branch that does not have a label. If a change had a score on a label that was only configured on the original branch, moving to a destination branch that did not have the label caused an internal error.
- Fix internal error when moving a change without specifying the destination. Omitting the destination branch in the input caused an internal error.
- Fix internal error when deleting a comment without providing input. The input is optional on the Delete Comment REST endpoint, but calling it without input resulted in an internal error.
- Fix internal error when rebuilding Note DB and a change is missing from Review DB.
- Fix omission of ‘branch’ values when saving project config. The ‘branch’ values were omitted when saving the config, resulting in them being lost.
- Issue 9195:
Strip comment lines out of commit message when creating change.
When a change was created from the UI (or via the ‘Create Change’ REST
API), and the commit message consisted of only a subject beginning with
a hash character (
#), the change was created with a zero Change-Id. This was because lines beginning with
#are considered to be comments, and are stripped from the commit message by JGit before computing the Change-Id for the commit. Before attempting to create the change, Gerrit now strips out any comment lines from the commit message and returns an error if this results in the commit message being empty.
- Issue 9389: Fix support for syntax highlighting of Clojure source files in the Polygerrit UI.
- Issue 5316: Fix incorrect relative URL paths in Gitiles links in the Polygerrit UI.
- Fix internal server error when generating email sender name for non-existing account.
--generate-http-passwordoption to the ssh
set-accountcommand. To bring the ssh command more in-line with the REST API for a user, it is now possible to generate a new HTTP password. This allows ordinary users to generate a new HTTP password via ssh when they cannot log in to the web UI (e.g. due to being a service account). Access to the
set-accountcommand is also relaxed; normal users may use it to set a new password on their own account.
- Sanitize values of
user.emailsettings were being read as-is, which would allow them to be configured with values that may interfere with standard email name/address parsing.
- Fix the default text in the ‘Password’ field on the ‘HTTP Password’ screen in the GWT UI. The default text said “(click ‘generate’ to revoke an old password)” but the label of the button is actually “Generate Password”.
- Add reporting of work queue related metrics. Metrics are reported for core work queues. For work queues created by plugins, metrics are not reported.
- Issue 8861: Fix generation of change numbers to prevent duplicates. When migration to NoteDb was aborted, and then started again later, generated change numbers overlapped with change numbers created in ReviewDb in the meantime.
- Issue 8931: Pass the project name to ‘change indexed’ event listeners. When NoteDb is enabled, the change information is stored in the project’s git repository. Without the project name, plugins were not able to retrieve the change information.
- Issue 8742: Fix infinite loop in intraline diff loader. A regression introduced in 2.15.1 caused excessive CPU usage when loading intraline diffs.
- Issue 8697:
Restore the ability to ignore invalid review labels.
In 2.15 the
strict_labelsattribute was removed from the review input entity, and Gerrit no longer silently ignores invalid label scores. This caused breakage in CI systems that submit reviews post-merge and don’t have different configurations for if the change is already merged or not. For example the Gerrit Trigger Plugin was broken, as discussed on the Gerrit mailing list. A new configuration
change.strictLabelsis introduced. When enabled, Gerrit will reject invalid labels, otherwise will silently ignore them. By default it is disabled, for backwards compatibility with previous releases.
- Issue 8728: Allow percent encoding in patch set titles.
- Issue 8850:
reviewerin:search results when user is added as CC. The
reviewerin:search should only return users that were added as a reviewer, but was also including users that were added as CC.
- Issue 8817: Fix internal server error when listing projects and a repository is not available. The new permission backend was throwing an error when a repository could not be found. Now it is simply omitted from the project list.
- Issue 8643: Properly display the status of “Work in Progress” changes. When a change was submittable (i.e. had all the necessary labels) but was still in the “Work in Progress” state, its status was displayed as “Merge Conflict” in the change list and the change screen in the GWT UI.
- Issue 8936: Add missing ‘Hashtags’ label on the change screen in the GWT UI.
- Issue 8916: Allow ownerin predicate to be evaluated by the index.
- Fix double creation of SSH command execution queues.
- Fix timestamp for submodule updates. When a submodule was updated by subscription, the same commit timestamp was always used due to the server identity being cached.
- Allow to include username in servlet response header.
http.addUserAsResponseHeader, the servlet response includes a ‘User’ header that contains the name of the logged in user, enabling reverse proxies to log the name of the user that issued the http request.
- Fix user permission checks in APIs when invoked via the GerritApi. Actions were incorrectly being denied because the user validation was comparing user object instances rather than the account ID that they represented.
- Allow to replace the default H2 persistent cache with a custom implementation.
The default H2 persistent cache can be replaced by a module that implements
CacheImplinterface. An implementation is provided for postgresql.
- Various logging improvements.
- Hooks plugin
- Issue 9015:
submithook is invoked synchronously when a change is submitted. If it returns a non-zero exit status, a
MergeValidationExceptionis thrown and the submit is prevented. This adds back the ability to block submit by a hook which was removed in version 2.14 due to the reworking of the
- Fix repeated instantiation of the
commit-receivedhooks. The hooks were not singletons, which caused new instances to be created on every invocation.
- Wrap account ID in quotes when passing as hook argument.
- Improve logging to make it easier to track down hook execution problems. When a hook exits with an error status (i.e. non-zero), or times out, an error is now emitted to the log. Previously there was no log on timeout, and the exit status was only logged at debug level. The configured hooks path and resolved path for hook files is logged at info level. When a hook file does not exist, a message is logged at debug level.
- Improve documentation
- Expand and improve documentation related to debugging hooks.
- Restructure the hooks page to separate synchronous and asynchronous hooks, and add a table of contents.
- Issue 9015: Add a
- Polygerrit fixes:
- Issue 8655: Clear suggestions on autocomplete input change.
- Issue 8237: Link account chips to owner search rather than user dashboard.
- Issue 8375: Add reset button to my menu in settings.
- Issue 7815: Don’t curse over files with up/down keys.
- Issue 8722: Limit assignee suggestion to users that can see the change. This was fixed for the GWT UI in 2.15.1.
- Issue 8940: Fix loading change edit on change screen.
- Issue 4552: Allow some sections of the change list to overflow
- Add a link to group page in groups section of settings.
- Make sure plugins are not double counted.
- Elasticsearch fixes
- Issue 8523:
Fix configuration of elasticsearch during site initialization.
When the site was initialized with Elasticsearch as the secondary index,
elasticsearch.prefixwas not set, and Elasticsearch server-specific settings were not correctly set under
- Issue 8527:
Improve documentation of
index.maxLimitfor Elasticsearch. When using Elasticsearch,
index.maxLimitshould not exceed the value of
index.max_result_windowconfigured on the Elasticsearch server.
- Issue 8553: Fix reindexing of an already initialized site with Elasticsearch.
- Issue 8690:
Allow to use the
index activatessh commands with Elasticsearch.
- Issue 8525: Fix setting of changed lines in the change info.
- Issue 8588: Fix setting the star icon status in the change info.
- Issue 8806: Fix online reindex to new index version.
- Change default Elasticsearch prefix to
- Issue 8523: Fix configuration of elasticsearch during site initialization. When the site was initialized with Elasticsearch as the secondary index, the
- Issue 8677: Fix internal error when sending raw input to PUT and POST REST endpoints. In particular, this caused errors when using the plugin manager to update or install plugins.
- Issue 5181: Limit assignee suggestion to users that can see the change.
- Issue 6112: Add support for “Included In” in the polygerrit change screen.
- Issue 6583: Fix false negatives for edits due to rebase.
- Issue 8574: Fix refesh of polygerrit change list with “Shift + R”.
- Issue 8703: Fix false warning in server log when creating a new project.
- Issue 8252: Improve error message in polygerrit when adding a group member to a group that does not exist or is not viewable for the current user.
- Allow admins to toggle the WIP flag on all changes.
- Fix internal server error when group UUID cannot be resolved when getting audit log.
- Display group UUID in group audit log if group name is missing. The group name can be missing if there is no group backend that handles the group. This can happen for example if a plugin that handled the group was removed.
- Fix removal of email/password on external ID update.
- Replication plugin:
- Fix creation of missing repository.
When replicating to a destination where the repository does not exist,
HEADreference failed because the passed reference name was not absolute.
- Add documentation of how to exclude repositories from replication.
- Fix logging of new project creation and project deletion. The “created” and “deleted” logs were emitted even when the operation failed.
- Fix creation of missing repository. When replicating to a destination where the repository does not exist, updating the
- Allow graceful rolling restarts Set a graceful stop timeout for allowing Jetty to wait for incoming requests to be completed before shutting down its sockets.