Download: 3.6.1 | 3.6.0

Documentation: 3.6.1 | 3.6.0

Release highlights

Gerrit 3.6 is fully compatible with Java 17 LTS.

Submit Requirements

Gerrit deprecates the use of Prolog for definition of custom logic in the submit rules. From this version onwards the rules can be expressed using the new concept of Submit Requirements.

Submit Requirements have several advantages, compared to the legacy Prolog rules:

  • Easier to understand, defined through simple boolean expressions using a higher-level change search predicates and common boolean operator.
  • Lower footprint: they do not require backtracking in their evaluation, consuming less CPU cycles.
  • Richer GUI: makes it easy for reviewers and change owners to identify and understand missing requirements.

Existing projects relying on Prolog will still work as expected, allowing a smoother project transition.

Submit requirements also introduce new handy functions that allow to achieve complex rules equivalent to the old Prolog rules but with an easier syntax:

  • support checking on content modifications and file diffs with the file: operator.
  • distinctvoters predicate allows gating submission on N distinct voters across more than one label.
  • authoremail operator similar to the older commit_author Prolog predicate
  • message predicate to support regular expression on the commit message as a condition.

NOTE: With the new submit requirements, submit records are no longer emitted. This means that any queries with the label formats (label:Code-Review=NEED or label:Code-Review=OK) will no longer match with changes. See more details in Change 330203.

Important notes

Schema and index changes

This release doesn’t formally contain schema changes, however the NoteDb format has evolved and includes the following amendments:

NOTE: Because of the above incompatibilities, upgrade is supported only from Gerrit v3.5.2 onwards, because of the need of the extra copy-approvals tool and the backward compatibility fix on UUID suffixed labels. Failing to run the copy-approvals tool in v3.5.2 would leave the changes with a potentially stale approval score once the site is migrated to v3.6.

The changes index version has been increased to version 77. By default the index is automatically rebuilt upon the Gerrit startup after the upgrade.

Offline upgrade

Upgrade to Gerrit v3.5.2 or later and make sure that the copy-approvals site program has been run at least once.

  java -jar gerrit.war copy-approvals -d site_path

Download the Gerrit v3.6.0 war and run the init program:

  java -jar gerrit-3.6.0.war init -d site_path

Run offline reindexing of the changes:

  java -jar gerrit.war reindex --index changes -d site_path

Online upgrade with zero-downtime

Gerrit v3.6.x supports zero-downtime upgrade from Gerrit v3.5.2 or later when configured using a high-availability configuration, and the Git repositories are stored in a shared filesystem such as NFS or similar.

During the zero-downtime upgrade, Gerrit end-users would not notice any outage or service disruption. They will be able to perform any read/write Gerrit operation on the GUI or using using any API.

The zero-downtime upgrade consists of the following steps:

  1. Have Gerrit servers running v3.5.2 or later, in high-availability configuration, healthy and able to handle the incoming traffic properly.
  2. Run the copy-approvals SSH command against one of the Gerrit servers and wait for completion on all changes for all projects.
  3. Set the Gerrit server unhealthy.
  4. Shutdown the Gerrit server, update gerrit.war and plugins to v3.6.x and start Gerrit again.
  5. Verify that the Gerrit server is working properly (e.g. run automated smoke tests) and then make it healthy again.
  6. Wait for the Gerrit server to start serving traffic normally.
  7. Repeat steps 3. to 6. for all the other Gerrit servers.

Breaking changes

  • Change 321607: Assignee feature is completely removed from the Gerrit UI

    The Attention Set feature has been launched in Gerrit v3.3, and assignee has been turned off by default for three releases. The feature is now completely removed and cannot be enabled anymore by config.

  • Project Owners implicit delete reference permission has been removed.

    Before this release all Project Owners had implicit delete permission to all refs unless force-push was blocked for the user. Admins that are relying on previous behavior or wish to maintain it for their users can simply add the permission explicitly in All-Projects:

      [access "refs/*"]
        delete = Project Owners

    NOTE: If you choose to do so, blocking force-push no longer has any effect on permission to delete refs by means other than git (REST, UI).

  • Support for CentOS is dropped and the base image replaced by AlmaLinux

    RedHat anticipated the EOL of CentOS to December 2021 making hard for the Gerrit community to continue to support existing Docker setups on CentOS. The default base image now uses AlmaLinux 8 which promises to have a much longer life as open-source OS and has an easy migration tool from CentOS 8 available.

  • Apache Commons Lang v2 is removed

    Gerrit moved to Apache Commons Lang v3 replacing all legacy use of the older lang v2 from its dependencies. Existing plugins and scripts that are using Apache Commons Lang v2 must be rebuilt to use the new library or declare the older Apache Commons Lang v2 as an explicit dependency.

Other changes

Plugin changes

  • Change 331259: Deprecate the registerStyleModule() JS plugin API

  • Change 330403: Support validation options for branch creation to be used in RefOperationValidationListener implemented in plugins.

  • Change 330200: Add support for specifying validation options in rebase and cherry-pick REST endpoint and implemented in plugins.

  • Upgrade to gitiles v1.0.0

Gerrit UI changes

  • Change 324242: Add syntax highlighting for Markdown

    Reuse and enable highlight.js syntax highlighting of Markdown files.

  • Issue 15715: Fix the editing workflow in the web app

  • Change 330301: Adding tab navigation for hovercards

  • Change 330919: Show Change actions regardless if logged in or not, because the gr-change-actions correctly hides the actions that the current user cannot do.

  • Change 333299: Remove the front-end metric diffViewFullyLoaded replaced by diffViewDiplayed to represent highlighting a whole file.

  • Change 330204: Adds changes and dashboard link to account hovercard.

  • Change 330084: Status field renamed to About me and no icon is shown.

Documentation changes

End-to-End tests changes

New test properties are available in the End-to-End tests:


JGit changes

  • Update jgit to v6.1.0.202203080745-r

    release notes: 6.0 6.1

    most important changes since 5.13:

    • [push] support the “matching” RefSpecs “:” and “+:”
    • IndexDiff: use tree filter also for SubmoduleWalk
    • Describe: add support for core.abbrev config option
    • PersonIdent: Add ctors that accept Instant in addition to Date
    • Cap describe abbrev option, minimum is 4, maximum is length of a full ObjectId
    • DescribeCommand: Add support for –abbrev=0
    • DescribeCommand: Support configuring the hash abbreviation
    • PushCommand: determine remote from git config if not given
    • PushCommand: consider push.default when no RefSpecs are given
    • Support for git config push.default
    • Support for “lfs.url” from “.lfsconfig”
    • Support LFS Server URL without .git suffix
    • [rebase] Enable users to have a Change-ID be generated when squashing or rewording commits.
    • RepoCommand: Add API to set extra files in the destination repository
    • RebaseCommand: better commit message rewording. Respect git config commit.cleanup for rewording.
    • CommitCommand: implement git commit –cleanup.
    • Provide git config commit.cleanup
    • sshd: support the ConnectTimeout ssh config
    • sshd: Skip unknown keys from the SSH agent
    • sshd: support the AddKeysToAgent ssh config
    • sshd: handle “IdentityAgent SSH_AUTH_SOCK” in ssh config
    • sshd: Connector for the Win32-OpenSSH SSH agent
    • sshd: handle IdentitiesOnly with an SSH agent
    • shd: support IdentityAgent config
    • Add config reader for user-defined difftools
    • Add command line support for “git difftool”
    • Transport: load all refs only if push refspecs have wildcards
    • UploadPack v2 protocol: Stop negotiation for orphan refs
    • PackBitmapIndexV1: support parallel loading of reverse index
    • RefDirectory.scanRef: Re-use file existence check done in snapshot creation
    • FileSnapshot: Lazy load file store attributes cache
    • Support commit.template git config option
    • ssh: Handle “ProxyJump none” from SSH config file
    • OpenSshConfigFile: update handling of line comments and quoted strings following changes in OpenSSH
    • OpenSshConfigFile: update token replacements. It appears that the OpenSSH documentation has changed; it now allows more flags for a number of keys.
    • [sshd agent] Introduce ConnectorDescriptor
    • sshd: add support for ssh-agent
    • Binary and CR-LF detection: conclude file is binary if it contains a lone CR like C git
    • Make the buffer size for text/binary detection configurable
    • GarbageCollectCommand: add numberOfBitmaps to statistics
    • Don’t block in GC#gc until garbage collection finished
    • Let ObjectDatabase implement AutoClosable
    • Optimize RevWalk.getMergedInto() to improve performance
    • improve how git system config is found
    • Bump minimum required Java version to 11
    • [checkout] Use .gitattributes from the commit to be checked out
    • [push] Call the pre-push hook later in the push process
    • Prevent that an instance of PushCommand is reused
    • Stop initCause throwing in readAdvertisedRefs
    • Make sure to close Repository in tests
    • Fix resource leak in CancellableDigestOutputStreamTest
    • RebaseCommand: fix commit message in “fixup” case
    • BinaryHunkInputStream: accept CR-LF
    • Merge conflict messages: prefix conflict lines with a hash
    • ObjectWalk: close ObjectReader on close() if needed
    • LFS: Fix error occurring during delete branch
    • sshd: backport upstream fix for SSHD-1231
    • Use FileSnapshot without using configs for FileBasedConfig
    • TreeRevFilter: fix wrong stop when the given path disappears
    • storage: file: De-duplicate File.exists()+File.isFile()
    • Fix checkout of files with mixed line endings on text=auto eol=crlf
    • Fix missing peel-part in lsRefsV2 for loose annotated tags
    • Fix RevWalk.getMergedInto() ignoring annotated tags
    • Reftable: close old Db in FileRepository#convertToPackedRefs
    • Reftable: Reload the stack before trying to delete the files. This ensures we don’t trip over our own open file handles when deleting compacted tables.
    • Reftable: drop code for truncated reads
    • Reftable: pass on invalid object ID in conversion

Other dependency changes

  • Update sshd to 2.8.0

    The highlights of SSHD update from Gerrit’s perspective are:

    • SSHD-1216: Server-side implementation of the RFC 8332 server-sig-algs extension: the server announces that it prefers the SHA-2 signatures for RSA keys.

    • SSHD-1197: A race condition in key exchange fixed.

    • SSHD-1163: DH group exchange got a fix relating to RSA SHA-2 signatures.

    Additionally, sshd 2.8.0 now supports (and prefers) the cipher SSHD-1017, and supports the curve25519 and curve448 KEX algorithms SSHD-704.

  • Update codemirror-minified to 5.65.0

  • Update highlight.js to 11.5.0

  • Update rules_nodejs version to 5.1.0

  • Update rules_go version to 0.30

  • Update protobuf version to 3.19.4

Other core changes

  • Change 334747: Fixed missing return type in e2e-tests

  • Change 334557: Make the computing of the diff cache thread-safe.

    The computation previously failed with a zlib exception that was logged as if the packfile was corrupt even though it wasn’t.

  • Change 333706: Added support for ‘is:' in approval copy condition queries to make arbitrary voting values sticky

  • Change 332139: Stop adding project-owners to To: of the emails for new changes.

Bugfix releases


  • Breaking changes

    • Issue 15941 Fix SSH queries to not show commit-message unless –commit-message is provided This issue has existed for several years and should be considered breaking as users might expect commit message to be included by default in SSH query results. Obtaining the commit message is a costly operation as the commit data has to be loaded. So, showing it even when –commit-message is not provided degrades the performance of SSH queries.
  • Performance Fixes

    • Change 338614 Optimize SSH queries to avoid loading individual accounts This improves performance of SSH queries.

    • Change 338834 Avoid creating an IdentifiedUser multiple times in a SSH query This improves performance of SSH queries.

    • Change 338574 Cache ProjectControl instances in SSH queries A PerThreadCache is used to cache ProjectControl instances to improve SSH query performance.

    • Change 338474 Allow async receive-commits to have a thread-local cache Improve caching when merging changes through git push

    • Change 338154 Lazy load change notes when submit by push Improves performance of change submit via push

  • Bug Fixes

    • Issue 15997 Make delegate() method public git-repo-metrics plugin now works with multi-site setup

    • Issue 15134 Apply the match operator to filter projects Next-arrow is now not hidden when searching for repositories in the Repository section

    • Change 337474 Use sane value for QueryProcessor’s effective limit on “–no-limit” Fix errors seen when –no-limit query option is used with ES index backend

    • Issue 16018 Don’t try to mark files as reviewed when not logged in Fix marking of reviewed flag when not logged in. “Log in is required to perform that action” popup is no longer seen when viewing file diffs unauthenticated.

    • Issue 16001 AsciiDoctor: skip attribute when looking for title Fix documentation search showing :linkattrs: instead of the document title

    • Issue 16038 Fix “internal error” when pushing to refs/users/xx/xxxx Push over HTTP to refs/users/* branch now works and doesn’t fail with “error: internal error” / Not Signed In

    • Issue 15946 gr-cla-view: remove old css that broke displaying claNewAgreement

  • Dependency Updates

  • Update JGit to 5efd32e91

  • Documentation Fixes

    • Change 340114 sshd config: Reference implementation sections upstream

    • Change 339819 Supplement key exchange supported by Apache MINA

    • Change 339818 Supplement ‘encrypt-then-MAC’ supported by Apache MINA

    • Change 339815 Supplement cipher algorithms in sshd.cipher section

    • Change 339235 Add copy-approvals SSH command link to the index page

    • Change 338949 Fix auto-generated documentation header for plugins

    • Change 337835 rest-api-projects: Fix documentation for #inherited-boolean-info


  • Bug Fixes

    • Issue 15957: Fix loading ssh and gpg keys in Gerrit UI and make the text areas have a white background

      The Gerrit UI did not display the list of the user’s SSH and GPG keys, even if they were present in the user’s profile and working as expected.

  • Other Fixes

    • Change 337014: Plugins named with hyphens can now define query operators