Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
The pg-plugin-checks-api documentation describes Gerrit’s JavaScript Plugin Checks API: a frontend interface that lets a PolyGerrit plugin show external CI, analysis, coverage, and other automated results on a change page. Its entry point is plugin.checks(). It is not a REST endpoint, does not run builds or store check history by itself, and is not the separate Gerrit Checks Plugin.
What “PG Plugin Checks API” means
“PG” is historical shorthand for PolyGerrit, Gerrit’s modern web interface and plugin framework. pg-plugin-checks-api is the documentation filename; the public concept is Gerrit’s JavaScript Checks API. A plugin uses it to contribute structured check information to a change. Gerrit presents that information in the Checks tab and change summary. Gerrit’s documentation says the Checks tab is hidden when no plugin has registered a Checks provider. Read the API documentation.
The API is a presentation and integration layer. It does not replace a CI system, execute jobs, automatically authenticate to external services, or provide a universal backend protocol.
How the data flows
External CI or analysis service
↓
Gerrit JavaScript plugin
↓
plugin.checks() and a registered provider
↓
Provider fetch() returns runs and results
↓
Gerrit Checks tab and change summaryThe plugin acts as an adapter: it obtains or transforms data from an external service, maps it into Gerrit’s check model, and returns that data to the UI. Potential sources include Jenkins, Buildbucket, GitLab CI, GitHub Actions, proprietary build services, static analyzers, coverage tools, security scanners, and deployment-preview systems. Gerrit’s documentation links to examples including Buildbucket and code-coverage integrations.
#1 Best Overall
Register a provider
The basic pattern is to obtain the API object and register a provider. The provider must implement fetch(), which returns a promise resolving to a response containing runs and results; configuration is optional.
const checksApi = plugin.checks();
const provider = {
async fetch(change) {
const response = await fetch(
`/my-ci-api/checks?change=${encodeURIComponent(change.change)}`
);
const data = await response.json();
return {runs: data.runs};
},
};
checksApi.register(provider);This is illustrative pseudocode, not a guaranteed copy-and-paste implementation. The exact types and required fields can vary by Gerrit version. Consult the Checks API TypeScript definitions for the Gerrit revision you target. The master definitions may be newer than a deployed server.
Runs and results
A run represents an execution or logical collection of checks; its results represent the individual checks within it. A response can contain multiple runs, and each run can contain multiple results. Results can provide status, a message, links, details, and identifiers. The detailed field-level shape belongs to the target version’s API definitions rather than a one-size-fits-all schema.
Free tools Windows power users keep installed
One-click scans. No signup required.
Map identities consistently. A result should correspond to the change and patchset it actually describes, and retries should be represented in a way that distinguishes attempts. This prevents an old successful run from appearing to describe a newer patchset. Stable identifiers also matter for incremental updates: updateResult() requires a result externalId.
Refreshing results with announceUpdate()
checksApi.announceUpdate();This tells Gerrit to call registered providers’ fetch() methods again. A plugin can use it after learning that data may have changed, such as after polling a CI service or receiving a webhook. It refreshes the provider’s data; it does not itself contact the CI system or accept a webhook.
- Debounce bursts of webhook events so they do not cause a cascade of redundant fetches.
- Avoid aggressive polling that overloads Gerrit or the external service.
- Handle timeouts and service failures explicitly. Distinguish unavailable data from a failed check.
- Do not silently label old results as current. If showing last-known information during an outage, make its age or stale state clear.
- Filter or map historical attempts deliberately to avoid duplicate current runs.
Load detailed results on demand
Build logs, lengthy test reports, and coverage details can make initial page loads slow and responses large. A common pattern is to return a concise summary first, then load richer content when a user expands a result. Gerrit documents the check-result-expanded plugin endpoint for this use case and provides updateResult(run, result) to update an individual result.
Rank #4
checksApi.updateResult(run, result);For this update, Gerrit locates the run using its change, patchset, attempt, and checkName properties. The result must have an externalId; an undefined value causes an error. This operation updates the matching result, not the whole run, and does not update the other run properties. Make sure the expanded result can be matched reliably, and provide visible loading and error states if fetching detail fails.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →For large payloads, show a short summary and an external log link initially; use a plugin UI such as a Web Component for structured detail when useful. This keeps the initial checks response lean while avoiding a blank or confusing expanded view when the detail service is unavailable.
Security and deployment considerations
A frontend plugin runs in a browser. Anything embedded in its JavaScript or delivered to the page should be treated as visible to users who can load that page. Do not put long-lived CI tokens or privileged credentials in plugin code. If external queries require secrets or elevated access, use a controlled backend proxy and enforce authorization there—not just in the UI.
- Check whether browser requests are permitted by the external service’s CORS policy and by the Gerrit deployment’s Content Security Policy.
- Validate change, patchset, and external identifiers before using them to query another system.
- Consider which users can see returned results and links, and avoid exposing data through a provider that users are not authorized to access.
- Use the external service’s API to start or rerun builds; registration and refresh methods are not build-control operations.
Checks API is not the Gerrit Checks Plugin
These names describe different things. The JavaScript Checks API is the frontend integration framework exposed through plugin.checks(). The Gerrit Checks Plugin is a separate plugin associated with an older Checks backend. Gerrit maintainer discussion distinguishes the supported JavaScript API from that deprecated plugin. The plugin’s deprecation does not mean the JavaScript Checks API itself is deprecated. See the maintainer clarification.
Is it a REST API?
No. register(), announceUpdate(), and updateResult() are frontend JavaScript methods on the object returned by plugin.checks(), not HTTP endpoints for posting results. A plugin may call a backend or external REST service as part of its implementation, but the Checks API itself is the browser-side integration surface.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Need | Usually appropriate |
|---|---|
| Display external check data in Gerrit’s modern change UI | JavaScript Checks API |
| Persist status or history server-side | A backend integration or external system of record |
| Start or rerun a build | The CI provider’s API, optionally called through a secure plugin/backend workflow |
| Show expanded check details | Checks API with the check-result-expanded endpoint |
| Discuss inline findings or suggested fixes | Gerrit review/comment mechanisms, where appropriate |
| Keep a long-term audit history | An external service or server-side integration |
Gerrit documentation has deprecated robot comments in favor of the Checks API and human comments in newer guidance, but that does not make comments universally unavailable or interchangeable with check summaries. Inline findings and review discussion may still call for comment workflows. See the robot comments documentation.
Version compatibility checklist
Before implementing or shipping a provider, check the Gerrit release actually deployed. Gerrit’s documentation is versioned, and current source definitions may be ahead of an installation. For example, the Gerrit 3.7.1 documentation is a release-specific reference; do not assume an example based on current master works unchanged on that or any other version.
Quick Recap
- Confirm the server version and consult its corresponding Checks API documentation and type definitions.
- Verify that your plugin API usage and the endpoints you need are available in that release.
- Check exact run/result fields against the release definitions, whether you use JavaScript or TypeScript.
- If supporting several Gerrit versions, account for API differences rather than assuming a single current schema.
Troubleshooting
- Checks tab is missing: confirm a Checks provider is registered and the plugin loads on the change page. The tab may be hidden when no provider is registered.
fetch()is not called or data is empty: check plugin initialization, provider registration, browser console errors, the external request, and the response mapping. Verify that the returned response contains runs in the shape expected by your Gerrit version.- Results appear under the wrong revision: inspect how the plugin maps change and patchset identifiers. Do not reuse a prior patchset’s status as current.
- Duplicate runs appear: check whether retries, history, polling, and webhook refreshes all contribute the same logical run. Choose a consistent attempt/run identity and filter intentionally.
updateResult()fails: ensure the result has a defined, stableexternalIdand that the run identity fields match the original run.- Expanded details do not load: confirm the
check-result-expandedendpoint is registered for the target release, the detail request succeeds, and the returned update targets the right result. Display a useful loading or error state. - External calls fail in the browser: inspect authentication, CORS, CSP, and network errors. Move privileged calls behind an authorized backend rather than exposing secrets in plugin code.
- Types or fields do not match: compare the implementation with the definitions for the installed Gerrit version, not only the latest
mastersource.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
