Gerrit 3.13.x | Gerrit Code Review

Documentation: 3.13.0-rc2

Release highlights

Introducing Gerrit Flows

A flow is an automation rule on a change that triggers actions on the change when the flow conditions become satisfied. For example, a flow can be an automation rule that adds a reviewer to the change when the change has been verified by the CI.

Flows can help to speed up the code review flow by automating actions, e.g. instead of monitoring the change manually until it gets verified by the CI and then manually adding a reviewer, the change owner may add a flow on upload that adds the reviewer automatically as soon as the CI verified the change.

Flows have stages, where the stages are only evaluated when all previous stages have been satisfied. This allows users to define chains of actions.

Conditions can be Gerrit conditions (e.g. “is the change verified?”) as well as conditions in third-party tools (e.g. “is the issue fixed?”).

The same is true for actions, some actions may be Gerrit actions (e.g. “add a reviewer”) but other actions may be actions in third-party tools (e.g. “close this issue”).

Since organisations running Gerrit have different third-party tools that they would like to integrate, the implementation of the flow service is pluggable through plugins.

Flow service implementations need to:

handle the storage of flows (e.g. in a database)
evaluate flows regularly (e.g. every minute) and trigger the flow actions when conditions are satisfied

NOTE: Gerrit Flows are experimental and available when the UiFeature__show_flows_tab flag is enabled.

Delete groups

The Gerrit internal groups deletion functionality is now complete, with the introduction of the delete button in the internal group details screen.

The backend support for removing groups was introduced with v3.12 however it wasn’t usable end-to-end in Gerrit yet.

The ability to remove groups is enabled by:

Set the groups.enableDeleteGroup to true
Enable the permissions to delete group as a global capability on All-Projects

NOTE: Groups cannot be deleted while they are referenced in projects ACLs.

Submit Requirements and Labels screens

The Submit Requirements and Labels associated with a Project are now accessible through two dedicated screen, which allows to list, create or amend the current ones.

The screen uses brand-new REST API that also allows the full automation of the listing, creation and edit of Submit Requirements and Labels via scripting, simpifying the automation of Projects setup.

Consistent change query results

Gerrit changes index may be temporarily out of synch with the underlying repository due to the lack of transactionality between the storage of the Git repository meta-data and the indexing process.

The misalignment between the index and the underlying Changes, or also the presence of corrupted Change meta-data on the repository, may result in an error screen as highlighted in Issue 440670261.

Introduce the is:consistent predicate to validate each record against the underlying repository, filtering out all the inconsistent entries and compensating temporary misalignment between the index and the repository.

NOTE: Checking the consistency of each Change returned by the index is expensive, hence the introduction of a predicate to do it on demand and only when needed. An example scenario is the Change index healthcheck that expects at least one item to return a positive result upon query.

OAuth bearer authentication

So far Gerrit only supported providing the OAuth token in the Authorization: Basic header. However, that is not the way proposed in the OAuth2 RFC, which suggests the Authorization: Bearer header, which is consequently used by most libraries.

This change adds support for using the Authorization: Bearer header. Gerrit then fully relies on the username provided in the token.

HTTP passwords replaced by auth-tokens

Move from long-lived HTTP passwords to time-limited authentication tokens to improve security and manageability. Tokens can be individually revoked, rotated, and scoped for specific use, reducing the risk of credential leaks. The number of tokens per user can be limited for avoiding eccessive slowdowns during authentication due to the multiple token validation lookups.

The new authentication tokens can also be associated with a maximum lifetime globally configured, for enforcing company policies on token expiration.

As part of this effort, the storage format for external IDs has been updated, and passwords in external IDs are now deprecated and its support is flagged for removal in future releases. Gerrit administrators can use a new offline migration tool for migrating all the HTTP passwords into authentication tokens and therefore removing all references to the deprecated HTTP password functionality.

UI updates and improvements

Several Polymer-based components were replaced with @material/web, as part of the ongoing effort to remove Polymer in a future release.
Plugins can now access @material/web components directly.
The AI-assisted “generate prompt” feature has been enabled by default and no longer hidden behind a feature flag.
Creating changes is now easier and more prominent — users can create a new change directly from the repository list.
The mobile UI has been redesigned for improved navigation, and the search bar has been refreshed for both mobile and desktop users.
Reviewers and CCed users can be moved via drag-and-drop.

Add scheduled reindexing of accounts

Add scheduled reindexing of accounts. Previusly scheduling reindexing was possoible for Changes, Projects and Groups.

Important Notes

Schema and index changes

Gerrit schema version is unchanged. No reindex is needed.

Offline upgrade

Stop Gerrit
Download the new gerrit.war and move it to $GERRIT_SITE/bin
Extract all the plugins from gerrit.war and move the ones needed into $GERRIT_SITE/plugins
Start Gerrit

Online upgrade with zero-downtime

Gerrit v3.13.x supports zero-downtime upgrade from Gerrit v3.12 when configured using high-availability setup.

During the zero-downtime upgrade, Gerrit end-users will not experience any outage or service disruption and will be able to perform any read/write Gerrit operation seamlessly.

The zero-downtime upgrade process for high-availability setups consists of the following steps (demo):

Have Gerrit servers running v3.12 in high-availability configuration, healthy and able to handle the incoming traffic properly.
Set one of the Gerrit servers to unhealthy.
Shutdown the Gerrit server, update gerrit.war, plugins and libs to v3.13.x and start Gerrit again.
Verify that the Gerrit server is working properly (e.g. run automated smoke tests) and then make it healthy again.
Ensure the Gerrit server is fully caught up with the events that happened while it was down before directing traffic to it.
Repeat steps 2 to 5 for each of the remaining Gerrit servers.

Downgrade

Downgrade to Gerrit v3.12 release is possible, but requires the following manual steps:

Stop Gerrit
Rollback the gerrit.war and plugins to the previous v3.12 version
Start Gerrit

Native packaging

Instructions on how to enable Gerrit native packages on Linux system can be found here.

The Docker-based distributions have been updated:

AlmaLinux bumped to 9.6
Ubuntu bumped to Eclipse Temurin 21.0.8_9-jdk-noble (24.04.3 LTS)

Breaking Changes

Change 499526, Change 499601 Disallow setting deprecated label functions via REST, all new labels are created as NoOp via REST API.

If a user attempts to create a label with a deprecated label function or to update an existing label to a deprecated label function we reject the request with `400 Bad Reuqest’. Deprecated label functions should no longer be used and submit requirements should be used instead.

When creating a new label via REST API, it is associated with the NoOp function.
Change 488061: Use full commit SHA1’s in file conflict markers.
Change 487442: ChangeQueryBuilder#label: Reject using user and group args together.

Using the user and group args together is not supported. Currently trying to use them together doesn’t fail, but silently ignores the user arg, which is bad. This is because both args result in setting the accounts variable and when we process the groups arg the value of accounts that has been set for the user arg gets overwritten.

This change may cause disruption to users. For example for projects that have a submit requirement configured that uses submittableIf = label:Code-Review=MAX,user=non_uploader,group=myGroup the submit requirement currently passes if a Code-Review=MAX vote from a user of the myGroup is present (but the user=non_uploader arg is ignored) and with this change it will start failing (because the user and group args cannot be used in conjunction).
Change 484723: Allow project owners and admins to always see refs/meta/config.

Project owners, users that have the Owner access right on refs/*, and administrators should always be able to see the `refs/meta/config’ branch.
Change 480721: Disable the creation of new Prolog rules with rules.allowNewRules by default.

Prolog rules have been deprecated since Gerrit 3.6 but it was still possible to create new ones in projects configuration. From now on, the rules.allowNewRules is set to false therefore new Prolog rules are blocked.
Change 480342: Remove option auth.cookieSecure.

Do not allow to configure explicitly if the “secure” cookie attribute should be set. Instead set the “secure” attribute automatically if the request was done over a secure protocol (https). This prevents that users can skip setting the “secure” cookie attribute when using a secure protocol.
Change 465369: Disable robot comments by default.

Change the default of the server config enableRobotComments from true to false.

This change is part of generally deprecating robot comments (in favor of checks). At the moment enableRobotComments can still be changed to true, but support for robot comments will soon be entirely removed.
Change 474301: Remove Robot Comments from Gerrit UI.
Change 468102: Remove feature of adding reviewers automatically from footers.
Change 480302: Set default of SMTP connect and socket timeouts to 10 seconds.
Change 480301: Set reasonable defaults for LDAP connect and read timeouts.

Set default of:
- ldap.connectTimeout to 10 seconds
- ldap.readTimeout to 1 minute
Change 480303: Set a reasonable default transfer.timeout of 1 minute.

Do not wait indefinitely for a single network read or write but timeout after a minute to allow other requests to make progress instead of blocking a thread for a long time.

New Features

Change 504121: Added support for jitter configuration in periodic job scheduling to allow a random delay to be added to the start time of periodic background jobs.

This is particularly useful in multi-primary setups, where multiple instances of the same job may be scheduled to run at the same time, leading to spikes in resource usage and potential conflicts. By introducing a randomized delay, we ensure a more staggered and balanced execution pattern across instances.
Change 502661: EvaluateChangeQueryExpression: Add use-index option to evaluate against the index.

Evaluating expressions that require checking if the change is submittable (e.g. “is:submittable”) triggers executing the submit requirements which can be expensive. This may be a problem when the EvaluateChangeQueryExpression REST endpoint is used to evaluate flow conditions (that often check if the change is submittable) because flow conditions are evaluated very frequently (e.g. every minute).

If we evaluate the expression against the change state in the index submit requirements don’t need to be executed, since the submit requirement results are stored in the index.
Change 500904: Add --queue option to filter tasks by queue in show-queue.
Change 501361: Support non_author/committer arg on label predicate in submit requirements.

Add new non_author and non_committer args for the label predicate that work for submit requirement expressions as follows:
- “label:Code-Review=+2,user=non_author”: matches with the change if it has a Code-Review+2 vote on the latest patchset from a Gerrit account that’s not the author of the latest patchset
- “label:Code-Review=+2,user=non_committer”: matches with the change if it has a Code-Review+2 vote on the latest patchset from a Gerrit account that’s not the committer of the latest patchset
Checking for non author/committer votes may make sense when changes are imported by service user.

Since the author/committer can be forged with the Forge Author/Committer permission requiring a non-author/committer approval is not sufficient to prevent self-approvals when this permission is assigned.
Change 500946: Add a REST endpoint to evaluate whether a change matches a query expression.

The new REST endpoint allows to evaluate whether a change query expression (e.g. “is:submittable label:Auto-Submit+1”) matches a change.

This is useful to evaluate Gerrit flow expressions or to test submit requirement expressions.
Change 498401: Add option to toggle HTTP password fallback.

If all HTTP passwords were already migrated to authentication tokens, Gerrit would still check the external IDs for HTTP passwords. This added unnecessary costs.

Now, the fallback can be switched off using the auth.httpPasswordFallbackEnabled option to avoid the additional lookups.
Change 494604: Add REST API endpoint to reduce auth token lifetime.

The REST API endpoint POST /config/server/reduce.token.lifetime can be used to reduce the lifetime of existing tokens exceeding a given limit.
Change 459866: Allow to generate tokens with the set-account command.
Change 497803: Add context option to the get-patch endpoint.

Introduce a new --context (or -U) parameter to the changes/{id}/revisions/{id}/patch REST endpoint. This allows users to specify the number of context lines to include in the generated patch file, similar to the git format-patch -U command.
Change 497586: CreateBranch: Add a source_ref input parameter.

Callers creating branches with a commit-id revision often know the ref where that commit currently exists. Accepting it as an input provides both a performance optimization (reachability and visibility are only checked against that one ref) and a functional improvement since object ids can now be discovered on refs outside of refs/heads/ and refs/tags/.
Change 497223: Add work in progress to related changes rest api.

This is to allow making it easier to identify a change that has work in progress set to true.
Change 496681: Allow changing project config through review if project is READ_ONLY or HIDDEN.
Change 496303: Added REST endpoint to list global labels.

Global labels can be added programmatically via the LabelType extension point. Add a REST endpoint to list the global labels. This REST endpoint could be used to query the global labels in order to show them in the web UI (e.g. under BROWSE > `Server Info’).
Change 496401: Project label configuration changes can now be saved for review.
Change 495922: Enable save for review on project config by default.
Change 495921: Added extension point to add labels programmatically.

The new extension point can be used to define a global label programmatically that applies to all projects (if overriding is disallowed). This is useful for plugins that require a label, as they don’t need to rely on the administrators to configure the label correctly (e.g. in All-Projects).

The new extension point is similar to the existing extension point that allows to define a global submit requirement programatically.
Change 494661: Add repo label management screen.

Project owners can now manage repository labels through a new `Labels’ screen in the repository settings.
Change 492104: Add new REST API to delete list of changes in a single request.

API takes a list of ChangeId/ChangeNumber in the request body and try to deletes the mentioned Changes and returns a response about the change deletions.
Change 492103: Return the base that was used when performing a merge in ConflictsInfo.

Knowing the base is useful for tools that use the conflicts information to support users with resolving conflicts.
Change 492781: Change authors can now use the Please Fix button on check comments.
Change 465368: Add notification about token expiry.

Users will get notified ~7d before their tokens expire and after their token has expired. These emails are being sent by a daily run background task.
Change 464601: Add REST API to migrate HTTP passwords to tokens.

So far, HTTP passwords could only be migrated offline or by each user regenerating their tokens.

This change adds a REST API to migrate all HTTP passwords to tokens. This will add the existing token with an optional default lifetime to the user’s ref and afterwards delete all passwords from the external IDs.
Change 456342: Use dedicated cache for HTTP passwords / tokens.

The new token cache will only be enabled, if the option auth.gitBasicAuthPolicy is either HTTP or HTTP_LDAP. Otherwise, tokens can still be accessed directly in notedb. However, note that the tokens will not be used for authentication in that case.
Change 457041: Implement support for authentication tokens.

This change adds the new notedb schema version that supports tokens. These tokens are stored in a file tokens.config in the user’s ref in All-Users. They are stored in git config format:
```
[token "some-token-id"]
  hash = bcrypt0:4:....
```
This change also adds REST API endpoints to create, list and delete tokens.
Change 489321: Don’t try to generate prompt for merge changes.

Gerrit’s GetPatch REST API does not support revisions with more than one parent. This caused an error, when the “Help me review” feature is enabled and a merge change is opened in the UI.

To improve the user experience, no prompt will be generated for merge changes. Instead a message informing the user that this scenario is not yet supported will be shown.
Change 483644: Expose setNoLimit method from the InternalQuery API.

Set noLimit from the queryChangesInIndex in the AllChangesIndexer class. This has an effect that, when paging through index query results, every next page size is multiplied by the factor of 10. For large result sets this should bring significant performance improvements. For example: for a result set of 100K entries:
- without this change we would get 100K/500 = 200 pages
- with this change we would get 4 pages: 500, 5000, 50000, 44500
Change 481052: Add before change action event.

This allows plugins to add additional checks before code approval actions.
Change 482922: Add an option to the Create Project REST endpoint to redo the project init.

ProjectCreator first creates the repository, then it initializes the project.

The project initialization consists out of setting HEAD, creating the project.config file in refs/meta/config and creating initial branches with empty commits.

This change adds a new init_only option to the Create Project REST endpoint that allows to redo only the project initialization. This does not override any existing project configuration. If a conflicting configuration already exists the request is rejected with `409 Conflict’.

In particular this means that this cannot be used to:
- reset HEAD
- reset the project.config
- create additional branches
This is important to prevent misuse, e.g. attempts to do no non-reviewed updates on existing projects.
Change 481026: Add a REST API for flows.

This change adds REST endpoints for creating, getting, listing and deleting flows.

Which permissions are required for creating, seeing and deleting flows depends on the flow service implementation.

If no flow service is bound (i.e. if no plugin that provides a flow service is installed) the flow REST endpoints return `405 Method Not Allowed’.
Change 473141: Support creating a branch on an initial empty commit from the web UI.

Add a new field to the Create Branch dialog for creating a branch on an initial empty commit.
Change 465861: Add an extension point to validate push options.

Allow plugins to validate push options. For example, to reject options (or a combination of options) or to emit a warning when a deprecated option is being used.
Change 473825: Support showing all labels in change list.

Configured using:
```
  [dashboard]
      showAllLabels = true
```
If set, all the applicable labels for the currently shown changes is displayed in the change list view, even ones that are not considered submit requirements.
Change 475821: Allow to configure server-wide defaults for boolean project configs.

Admins can set global defaults in gerrit.config (true/false) or enforce them with `forced’, overriding project-level settings. This allows consistent defaults and enables enforcing options such as rejecting implicit merges across all projects.

Performance improvements

Change 494961: Speed up parent data computation.

What makes the parent data computation slow is checking whether the commit is merged into the target branch. If we have a change for the parent commit we can just skip this computation and instead check whether the status of the parent change is merged.
Change 473823: Make updating disk caches during offline reindexing optional.

Add a read-only H2 cache store that can optionally be used during offline reindexing. Using that, values will still be cached in memory, but the persisted caches will not be updated and only read from.
Change 506123: Persist changes_by_project cache to disk.

changes_by_project cache now stores its data in a serialized format on disk, reducing the need to rebuild the cache after server restarts, minimizing cache warm-up times and improving runtime performance.

Bug fixes

Change 472506: Remove orphan index-only entries without an underlying Change after (re)index with --reuse option

Reindexing with the --reuse option may result in having orphan index entries for which changes do not exist anymore. This change adds index cleanup step which is performed after reindexing is done, so that the orphan entries are cleaned up.
Change 512587: Fix shutdown of executor persisting cache updates in background thread.
Change 512503: Don’t close h2 database when last connection is closed.
Change 512281: Explicitly shutdown h2 database when SqlStore is closed.
Issue 446722017 Change 512122: Create h2 schema only once when SqlStore is created.
Issue 446941362 Change 512541: Fixed git-upload-pack errors on replicas by skipping unloadable changes.
Change 510885: Fixed changes_by_project cache to handle private changes with no reviewers.
Change 509082: Schedule configs with invalid time units now cause scheduling failures instead of using a default value.
Change 470262: Fixed docs to reflect assets under /static/ are cached at most 15 minutes.
Issue 375097838 Change 479024: Avoid pass-by-reference of hashtags.

This change resolves a bug where hashtags from a previous change were being incorrectly propagated to new changes in the same series during a push.
Change 463421: GitFileDiffCacheImpl: cancel tasks failing due to timeout or interrupt.

This avoids the task continues consuming resources unnecessarily. This may help to avoid unnecessary computations and return the thread executing the task earlier to the ExecutorService where it can be used to schedule other tasks waiting for an execution thread.

Frontend changes

Change 502622: Added auto-complete for hasfooter search operator.

See documentation.
Change 486462: Switch @webcomponents/webcomponentsjs to use the loader.

This change improves frontend performance by loading only the necessary polyfills for browsers that require them, reducing unnecessary overhead on the browser.
Change 511306: Fix bug with deleting permissions in handleAddedPermissionRemoved.

This bug occured for example if you add Delete Own Changes and Delete Changes. When you click remove on Delete Own Changes, it would delete both Delete Own Changes and Delete Changes but on the later, it would add a undo button.

Now the undo button should only be shown if the permission was saved previously, and also Delete Changes shouldn’t have been deleted as you didn’t click the remove button on that.
[Issue 397701289](https://issues.gerritcodereview.com/issues/397701289] Change 509464: Notify reviewers and watchers on change edit in UI.

Previously email notifications weren’t sent.
Change 488077: Support creating symlinks in change edits.

A symlink is a special type of file that acts as a shortcut, pointing to another file or directory.

There is no content validation for symlinks, i.e. we do not validate that the content of the symlink file is a file path (JGit accepts any content).
Change 488365: Copy conflict information when commit message is updated.

The Set Commit Message REST endpoint updates the commit message by amending the patch set commit. If the patch set commit was created by performing a merge (e.g. a merge commit, a cherry-pick commit or a rebased commit) and contains conflicts, the conflicts are preserved and the conflicts information is still accurate. Hence we should copy it over to the new patch set.

This is important if tools rely on the conflicts information to support users with resolving them.
Change 471081: Enable keyboard shortcut for download dialog up to 9.
Change 463141: Allow opening edit preference in editor view.
Change 471481: Add plugin api to add custom emojis.
Change 478021: Add Copy-to-Clipboard for Patch File.

This change introduces a “Copy to Clipboard” button in the download dialog for patch files. Users can now directly copy the raw diff content to their clipboard without needing to download the patch file first.

Other Changes

Change 499144: Fixed git-push-review python3 with shebang line update.
Change 462243: Add tool to adapt auth token lifetime to lower max lifetime.

Documentation changes

Change 502621: Document and test that footer keys with underscore cannot be matched.
Change 500401: Clarify that Gerrit HTTP passwords are limited to 71 chars.
Change 498459: Add note about legacy HTTP password in account to UI.

Plugin changes

Change 475523: Update CodeMirror.

codemirror/view contains a fix for the highlight of trailing spaces.

Updates the following:
- @codemirror/commands -> 6.8.1
- @codemirror/lang-javascript -> 6.2.4
- @codemirror/lang-python -> 6.2.1
- @codemirror/language -> 6.11.0
- @codemirror/legacy-modes -> 6.5.1
- @codemirror/lint -> 6.8.5
- @codemirror/search -> 6.5.11
- @codemirror/view -> 6.36.8

JGit Changes

Change: Update JGit to d6923d699

  $ git log --oneline --no-merges 7a46fa6f8...d6923d699

Notable changes are:

acd1eff8b PendingGenerator: drop only buffers loaded in the generator
8fd4cf3de Do not include 3rd party dependencies in features
e109bad94 Ensure pack files are closed after git.close()
2b64b5c6f WindowCursor: honor pack.useObjectSizeIndex
6ebd2f5d7 Prevent CommitGraphWriter.write() from closing its stream
1c0df9426 Make CancellableDigestOutputStream extend FilterOutputStream
5155683dc Shortcut PackWriter reuse selection when possible
a762badfc SmartHttpFetchConnection: suppress errors on close()
01123ee70 Mark Git(Repository repo, boolean closeRepo) public
ee304e465 Use volatiles for bitmap and revIndex in Pack
37d1a65f0 Fix performance regression in Pack.idx()
d9aba160b Use representation from LocalObjectToPack if possible
6c8d6e299 Avoid conditional in LocalObjectRepresentation.wasDeltaAttempted
ca6d673d5 Use chunked encoding when uploading LFS objects
c86cdcb96 WindowCursor: Use the object size index when possible
a673f022a GC: Write object size index if config says so
d9ac2f31e ObjectDirectoryPackParser: Write object-size index with the pack
8929300aa PackInserter: write object-size index with the pack
427af1262 Pack: getter for the indexed object size (when available)
896d07370 AmazonS3: Do not accept DOCTYPE and entities
8d30b5a75 ManifestParser: Do not accept DOCTYPE and entities
518cc54f8 AdvertisedRequestValidator: fix WantNotValidException caused by race
c3f354edc Lock reftable auto-refresh to ensure consistency
7c7f7d32e MultiPackIndexLoader: Add NON-NLS annotation to message
9fb0c4fca ChangedPathFilter: Suppress nls warnings in toString
3f3f3b5a6 Fix: Close the “preserved” PackDirectory
1c7289509 Use the same ordering/locking in delete() as C git
3e0eedc57 AmazonS3: Do not accept DOCTYPE and entities
07d00f6df ManifestParser: Do not accept DOCTYPE and entities
98494cd1a FS.getFileStoreAttributes: cancel failed task executed asynchronously
dab4f52d4 ManifestParser: Do not accept DOCTYPE and entities
4919c2b70 FileReftableStack: ensure new reftable files aren’t missed on NFS
f96e5e3b4 Encapsulate layout of reftable stack in FileReftableStack
43d3bc6d6 PlotWalk: Replace call to deprecated method in PersonIdent

Other dependency changes

Update Update h2 to 2.4.240
Update lucene to 10.2.2
Update guava to 33.4.8-jre
Update Apache mina-core to 2.2.4
Update apache sshd to 2.16.0
Update lit to ^3.3.1
Upgrade ICU4J to 77.1
Update typescript to 5.8.3
Upgrade eslint to 9.26.0