Gerrit Integration

Overview

ZeroPath supports Gerrit Code Review as a VCS provider. After connecting a Gerrit server, you can import its projects as ZeroPath repositories, run full scans against a project’s branches, and have ZeroPath scan open changes as new patch sets are pushed. Gerrit’s equivalent of a pull request is a change, and each revision of a change is a numbered patch set. ZeroPath scans the current patch set of an open change and posts its findings back as a review message on that patch set.

ZeroPath connects to Gerrit over HTTPS only. The credential is an account’s Gerrit HTTP password, which is sent as HTTP Basic authentication on every request, so an unencrypted connection would expose it.

Prerequisites

A ZeroPath organization where you can create VCS installations and repositories.
A Gerrit server reachable from ZeroPath over HTTPS. Gerrit 3.2 and later are supported.
A Gerrit account for ZeroPath to act as. A dedicated service account is recommended so that ZeroPath’s review messages are attributable and its access can be revoked independently.
That account needs Read access to every project you want to scan. It does not need any labels/voting permission — ZeroPath deliberately does not vote on Code-Review or Verified.

Generate an HTTP password

Open HTTP credentials

Go to Settings → HTTP Credentials.

Generate the password

Click Generate Password and copy the value. Gerrit shows it once.

Connect Gerrit

Open Gerrit setup

On a self-hosted ZeroPath deployment (zeropath.com does not offer Gerrit), open Repositories, click Add repository, select the Gerrit tab, then click Setup Gerrit.

Enter your server URL

Enter the URL of your Gerrit server, for example https://gerrit.example.com. If Gerrit is reverse-proxied under a path prefix, include it — https://example.com/gerrit is a valid server URL and the prefix is preserved.

Enter the account username and HTTP password

Use the Gerrit account’s username (not its email) together with the HTTP password you generated above. ZeroPath verifies the credential immediately by calling Gerrit’s /a/accounts/self endpoint, and stores the password encrypted at rest.

Import projects

ZeroPath lists every project the account can read — including servers with thousands of projects, which are paged completely. Select the projects you want to scan and import them, or choose Add all accessible Gerrit repositories to import every listed project in a background job that survives restarts and reports its progress in the dialog. Each imported project becomes a ZeroPath repository. Importing does not start scans.

Gerrit’s built-in All-Projects and All-Users, and any other permission-only parent project (a project whose HEAD points at refs/meta/config rather than a branch), hold no code. They are left out of the import list and are skipped by Add all; selecting one explicitly is refused with a message. A project that exists but has no commits yet is imported with no default branch and picks one up once something is pushed.

How change scanning works

ZeroPath scans the current patch set of an open change and posts findings back as review comments. There are two ways a change scan can be triggered, selectable per connected server:

Discovery mode	How it works	When to use it
Polling (default)	ZeroPath polls the server for open changes every few minutes.	Zero setup; no inbound access to ZeroPath required.
CI-triggered	Your own CI (e.g. a Jenkins job fired by the Gerrit Trigger plugin) calls the `scans.scanGerritChange` API endpoint.	You already run CI on every patch set and want scans to start immediately — and optionally to gate submission on the result.

Both modes stage the same scan through the same pipeline: identical deduplication (an already-scanned patch set is never rescanned), work-in-progress handling, and billing. Switch modes per installation under Settings → Integrations → Gerrit with the Change discovery toggle; setting it to CI-triggered stops ZeroPath from polling that server for changes (project discovery keeps running so repository import still works).

Polling (default)

Gerrit’s core distribution does not include webhooks — event delivery requires the optional webhooks plugin and inbound network access from your Gerrit server to ZeroPath. To avoid requiring either, ZeroPath polls each connected Gerrit server for open changes. Polling needs only the outbound access ZeroPath already requires in order to clone.

Open changes are polled every few minutes. A single query covers every project on the server. Change polling is independent of the project-list refresh, so a server whose project listing fails or is slow keeps getting its changes scanned.
When a change has a patch set ZeroPath has not scanned, a PR scan is queued for it. The patch set is fetched from its refs/changes/... ref.
Pushing a new patch set queues a new scan; a patch set that has already been scanned is never rescanned.
Changes marked work in progress are skipped until they are ready for review.
A project must have PR scanning enabled in its ZeroPath repository settings for its changes to be scanned.

CI-triggered (Jenkins)

If your Gerrit server already drives a CI system, that CI can trigger ZeroPath change scans directly instead of waiting for the poll:

curl -s https://zeropath.com/api/v2/scans/scanGerritChange \
  -H "X-ZeroPath-API-Token-Id: $ZP_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZP_TOKEN_SECRET" \
  -H "Content-Type: application/json" \
  -d "{\"changeUrl\": \"$GERRIT_CHANGE_URL\", \"patchset\": $GERRIT_PATCHSET_NUMBER}"

The change is re-fetched from your Gerrit server before anything is staged, so the request body is only a hint — ZeroPath never trusts CI-supplied data about what to scan.
The response includes the staged scan ids, which your job can poll via scans.get to wait for the result and fail the build on findings. With the Jenkins Gerrit Trigger plugin, a failed build votes Verified -1, which blocks submission under standard submit rules — giving you a security gate without ZeroPath ever voting itself.
Passing patchset protects against out-of-order CI events: if that patch set is no longer current, the request is rejected with 409 instead of scanning newer code under an old event.
Re-triggering an unchanged patch set returns already_scanned together with the existing scan ids, so retried CI jobs behave well.
The work-in-progress and PR-scanning-enabled rules above apply to CI-triggered scans too.

A ready-made Jenkins Shared Library wrapping all of this (trigger, wait, gate) is available at ZeroPathAI/zeropath-gerrit-jenkins. For self-hosted ZeroPath deployments, replace https://zeropath.com with your own instance URL.

Project states

ZeroPath records Gerrit’s own project state and treats it as follows:

Gerrit state	Behavior in ZeroPath
`ACTIVE`	Fully supported.
`READ_ONLY`	Scanned normally. Gerrit rejects writes to the project.
`HIDDEN`	Treated as archived and excluded from the list of importable projects. Already-imported repositories keep their scan history.
permission-only (`HEAD` = `refs/meta/config`)	Not a code project; excluded from bulk import and refused on explicit selection.

Inline comments and review messages

When a PR scan finds a vulnerability that maps to a specific file and line in the change’s diff, ZeroPath posts an inline comment on that file and line (via Gerrit’s review comments API), opening an unresolved thread. Findings that cannot be anchored to a diff line are posted as a general review message on the change instead. Because Gerrit’s published comments are immutable, updating a comment (for example, to add a patch link after a fix is generated) appends a reply in the same thread rather than editing the original. The thread remains open and the new information is visible directly below the original finding comment. When the finding is resolved, ZeroPath posts a final reply marking the thread resolved. ZeroPath never votes on Code-Review, Verified, or any other Gerrit label — whether a change is submittable stays entirely under your Gerrit configuration’s control. Scan status is posted as a review message tagged autogenerated:zeropath so Gerrit collapses it in the change log by default.

Current limitations

ZeroPath posts findings as a review message on the change. It does not vote on Code-Review, Verified, or any other label — whether a change is submittable stays entirely under your Gerrit configuration’s control. (A CI-triggered pipeline can still gate submission by failing its build on findings and letting the CI system vote — see above.)
With poll-based discovery, a scan starts within a few minutes of a patch set being pushed rather than instantly. Use CI-triggered discovery for immediate scans.
ZeroPath can generate patches for Gerrit findings, but cannot yet submit a patch as a new Gerrit change; the refs/for/<branch> submission path is not implemented.
@zeropath bot commands, which are available on GitHub, GitLab and Azure DevOps pull requests, are not yet available on Gerrit changes.
Gerrit servers presenting a certificate from an internal certificate authority are not yet supported; the server’s certificate must chain to a publicly trusted root.

Getting Started

Assets

Findings

Scanning

SCA

Platform

Developer Tools

Integrations

Authentication

Overview

Prerequisites

Generate an HTTP password

Connect Gerrit

How change scanning works

Polling (default)

CI-triggered (Jenkins)

Project states

Inline comments and review messages

Current limitations

​Overview

​Prerequisites

​Generate an HTTP password

​Connect Gerrit

​How change scanning works

​Polling (default)

​CI-triggered (Jenkins)

​Project states

​Inline comments and review messages

​Current limitations

Overview

Prerequisites

Generate an HTTP password

Connect Gerrit

How change scanning works

Polling (default)

CI-triggered (Jenkins)

Project states

Inline comments and review messages

Current limitations