---
title: "Trigger a Gerrit change scan from CI"
method: POST
path: "/api/v2/scans/scanGerritChange"
tags: ["Scans"]
---

# Trigger a Gerrit change scan from CI

`POST /api/v2/scans/scanGerritChange`

## Request

- Base URL: `https://zeropath.com`
- URL: `https://zeropath.com/api/v2/scans/scanGerritChange`
- Auth: API key in header `X-ZeroPath-API-Token-Id` and API key in header `X-ZeroPath-API-Token-Secret`

Stage a scan of a Gerrit change’s current patch set (the Gerrit equivalent of a PR scan), for use from an external CI system such as a Jenkins job fired by the Gerrit Trigger plugin. The change is re-fetched from the connected Gerrit server before anything is staged, so the request payload is a hint rather than trusted input. Staging matches the built-in change poller exactly: the same deduplication (re-triggering an unchanged patch set returns `already_scanned` with the existing scan ids), the same work-in-progress and PR-scanning-disabled skips, and the same credit admission. Results are posted back to the change as review comments, as with poller-discovered scans. To stop ZeroPath from also polling the server for changes, switch the installation’s change discovery to CI-triggered in Settings → Integrations.

## Request body

- union: Input for a CI-triggered Gerrit change scan. Address the change either by its web URL (e.g. the Gerrit Trigger plugin’s $GERRIT_CHANGE_URL) or by project and changeNumber — one or the other, not both.
  - object
    - `changeUrl` string, uri, required: Full Gerrit change URL. Accepts modern /c/{project}/+/{number} URLs and the /c/{number}, number-only, or #/c/{number} forms emitted by Gerrit and the Jenkins Gerrit Trigger plugin.
    - `patchset` integer: Optional staleness guard: the patch set number that fired the CI job (e.g. $GERRIT_PATCHSET_NUMBER). When it is no longer the change’s current patch set, the request is rejected with 409 instead of scanning newer code under an outdated event.
    - `installationId` string: ID of the connected Gerrit server. Required only when the URL matches more than one connected installation.
    - `organizationId` string: Organization ID (optional; defaults to the API token’s organization)
  - object
    - `project` string, required: Gerrit project name (e.g. $GERRIT_PROJECT).
    - `changeNumber` integer, required: Numeric Gerrit change number (e.g. $GERRIT_CHANGE_NUMBER).
    - `patchset` integer: Optional staleness guard: the patch set number that fired the CI job (e.g. $GERRIT_PATCHSET_NUMBER). When it is no longer the change’s current patch set, the request is rejected with 409 instead of scanning newer code under an outdated event.
    - `installationId` string: ID of the connected Gerrit server. Required when the organization has several Gerrit servers connected.
    - `organizationId` string: Organization ID (optional; defaults to the API token’s organization)

## Response `200`

Trigger result

- union: Result of a CI-triggered Gerrit change scan request
  - object
    - `outcome` 'staged' | 'already_scanned', required: What happened to the change. `staged` means scans were created; `already_scanned` means the current patch set already has scans (returned in `scans`); the rest mean the change is not scannable in its current state (work-in-progress, PR scanning disabled, project not imported, or out of scan credit).
    - `scans` object[], required: Scans for the current patch set, one per authorized repository partition that was newly staged or already scanned. Poll each with scans.get; ids are stable for the whole scan lifecycle.
      - `scanId` string, required
      - `repositoryId` string, required
    - `changeUrl` string, required: Canonical web URL of the change, as stored on the scans
    - `patchset` integer, required: The change’s current patch set number
  - object
    - `outcome` 'skipped_wip' | 'pr_scanning_disabled' | 'unmapped_project' | 'credit_blocked', required: What happened to the change. `staged` means scans were created; `already_scanned` means the current patch set already has scans (returned in `scans`); the rest mean the change is not scannable in its current state (work-in-progress, PR scanning disabled, project not imported, or out of scan credit).
    - `scans` object[], required: Scans for the current patch set, one per authorized repository partition that was newly staged or already scanned. Poll each with scans.get; ids are stable for the whole scan lifecycle.
      - `scanId` string, required
      - `repositoryId` string, required
    - `changeUrl` string, required: Canonical web URL of the change, as stored on the scans
    - `patchset` integer, required: The change’s current patch set number

## Other responses

- `400`: Error Response
- `401`: Error Response
- `403`: Error Response
- `404`: Error Response
- `409`: Error Response
- `500`: Error Response

---

[API](https://skmtc.dev/zeropath/apis/zeropath-api.md) - [All operations](https://skmtc.dev/zeropath/apis/zeropath-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zeropath/apis/zeropath-api/revisions/126e9c80ba0d?raw)