zeropath-gerrit-jenkins

Jenkins Shared Library (plus a plain-bash fallback) for triggering ZeroPath security scans of Gerrit changes from your own CI, waiting for the result, and blocking submission on findings.

ZeroPath scans Gerrit changes (Gerrit's pull-request equivalent) and posts findings back as review comments on the change. Out of the box it discovers new patch sets by polling your Gerrit server. If your Gerrit already drives Jenkins via the Gerrit Trigger plugin, this library lets that same event trigger the ZeroPath scan instead — scans start immediately, and your build can gate submission on the result.

Gerrit patchset-created ──► Jenkins (Gerrit Trigger) ──► zeropathGerritScan()
                                                             │  trigger + wait
                              Verified -1 on failure ◄───────┘  fail on findings

ZeroPath itself never votes on labels — submittability stays under your Gerrit configuration's control. The gate works because a failed build makes the Gerrit Trigger plugin cast its configured vote (typically Verified -1).

Prerequisites

• A ZeroPath organization (cloud at https://zeropath.com, or your self-hosted instance) with your Gerrit server connected and projects imported — see the Gerrit integration docs.
• A ZeroPath API token (dashboard → Settings → API). Store it in Jenkins as a username/password credential: username = token id, password = token secret.
• Jenkins with the Gerrit Trigger plugin (for event-driven jobs) and the Pipeline Utility Steps plugin (for the shared-library step). curl on the agent.
• Jenkins must be able to reach the ZeroPath API over HTTPS. For self-hosted ZeroPath this is in-network; nothing needs to reach out to the internet.

Setup

1. Configure the shared library — Manage Jenkins → System → Global Trusted Pipeline Libraries → add zeropath-gerrit, default version main, source this repository. Air-gapped environments: vendor this repository into your internal SCM and point the library there instead.

2. Create the credential — e.g. id zeropath-api-token, kind Username/Password, username = ZeroPath token id, password = token secret.

3. Use the step — see examples/Jenkinsfile:

   @Library('zeropath-gerrit') _
   
   zeropathGerritScan(
     // apiBase: 'https://zeropath.example.com', // self-hosted; omit for cloud
     credentialsId: 'zeropath-api-token',
     waitForCompletion: true,
     failOnFindings: true,
   )

   In a job fired by the Gerrit Trigger plugin, the change, patch set, and project are read from the trigger's environment automatically.

4. Turn off polling (optional but recommended) — in ZeroPath, Settings → Integrations → Gerrit → set the installation's Change discovery toggle to CI-triggered. ZeroPath then stops polling that server for open changes and your CI is the only trigger. (Project discovery keeps running, so importing repositories still works. Triggering also works with polling left on — scans are deduplicated per patch set — polling just becomes redundant.)

Step reference: zeropathGerritScan(Map config)

Key	Default	Meaning
apiBase	https://zeropath.com	ZeroPath URL. Self-hosted deployments must set this to their instance URL.
credentialsId	zeropath-api-token	Jenkins username/password credential holding the API token id/secret.
changeUrl	$GERRIT_CHANGE_URL	Change web URL. Alternative: project + changeNumber.
project, changeNumber	$GERRIT_PROJECT, $GERRIT_CHANGE_NUMBER	Used when changeUrl is absent.
patchset	$GERRIT_PATCHSET_NUMBER	Staleness guard: if this patch set is no longer current, the step logs and skips (HTTP 409) instead of scanning newer code under an old event.
installationId	—	Only needed when the organization has several Gerrit servers connected and addressing by project + changeNumber.
organizationId	token's organization	Rarely needed.
waitForCompletion	true	Poll scans/get until every triggered scan finishes.
timeoutMinutes / pollSeconds	30 / 30	Wait behavior.
failOnFindings	true	Fail the build when a finished scan reports open findings (a change's newly introduced findings).

Returns the trigger response (outcome, scans, changeUrl, patchset); with waitForCompletion the per-scan results are added under results. Re-triggering an already-scanned patch set is safe: the API returns already_scanned with the existing scan ids, so the wait/gate still works.

Freestyle jobs / other CI systems

scripts/zeropath-gerrit-scan.sh does the same thing with bash + curl + jq, configured entirely through environment variables (ZEROPATH_API_BASE, ZEROPATH_TOKEN_ID, ZEROPATH_TOKEN_SECRET, plus the standard GERRIT_* variables). Exit code 1 on findings.

API

Both entry points wrap two ZeroPath endpoints, documented in the API reference:

• POST /api/v2/scans/scanGerritChange — stage a scan of a change's current patch set. ZeroPath re-fetches the change from your Gerrit server before staging, so the request is a hint, never trusted input.
• POST /api/v2/scans/get — poll a scan by id until finished.

License

MIT