> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerrit Integration

> Connect a self-hosted Gerrit Code Review server to ZeroPath for full scans and change (patch set) scanning

## Overview

ZeroPath supports [Gerrit Code Review](https://www.gerritcodereview.com/) 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.

<Note>
  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.
</Note>

## 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

<Steps>
  <Step title="Sign in as the ZeroPath service account">
    Sign in to your Gerrit web UI as the account ZeroPath will use.
  </Step>

  <Step title="Open HTTP credentials">
    Go to **Settings → HTTP Credentials**.
  </Step>

  <Step title="Generate the password">
    Click **Generate Password** and copy the value. Gerrit shows it once.
  </Step>
</Steps>

## Connect Gerrit

<Steps>
  <Step title="Open Gerrit setup">
    In ZeroPath, go to **Add Repositories** and select the **Gerrit** tab, then click
    **Setup Gerrit**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Import projects">
    ZeroPath lists every project the account can read. Select the projects you want to scan and
    import them. Each imported project becomes a ZeroPath repository.
  </Step>
</Steps>

## How change scanning works

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.
* 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.

## 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. |

## 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.
* Change discovery is poll-based, so a scan starts within a few minutes of a patch set being
  pushed rather than instantly.
* 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.