| :linkattrs: |
| = Gerrit Code Review - JavaScript Plugin Checks API |
| |
| This API is provided by link:pg-plugin-dev.html#plugin-checks[plugin.checks()]. |
| It allows plugins to contribute to the "Checks" tab and summary: |
| |
| image::images/user-checks-overview.png[width=800] |
| |
| Each plugin can link:#register[register] a checks provider that will be called |
| when a change page is loaded. Such a call would return a list of `Runs` and each |
| run can contain a list of `Results`. |
| |
| The details of the ChecksApi are documented in the |
| link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui/app/api/checks.ts[source code]. |
| Note that this link points to the `master` branch and might thus reflect a |
| newer version of the API than your Gerrit installation. |
| |
| If no plugins are registered with the ChecksApi, then the Checks tab will be |
| hidden. |
| |
| You can read about the motivation, the use cases and the original plans in the |
| link:https://www.gerritcodereview.com/design-docs/ci-reboot.html[design doc]. |
| |
| Here are some examples of open source plugins that make use of the Checks API: |
| |
| * link:https://gerrit.googlesource.com/plugins/checks/+/master/web/plugin.ts[Gerrit Checks Plugin] |
| * link:https://chromium.googlesource.com/infra/gerrit-plugins/buildbucket/+/main/web/plugin.ts[Chromium Buildbucket Plugin] |
| * link:https://chromium.googlesource.com/infra/gerrit-plugins/code-coverage/+/main/web/plugin.ts[Chromium Coverage Plugin] |
| |
| [[register]] |
| == register |
| `checksApi.register(provider, config?)` |
| |
| .Params |
| - *provider* Must implement a `fetch()` interface that returns a |
| `Promise<FetchResponse>` with runs and results. See also documentation in the |
| link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui/app/api/checks.ts[source code]. |
| - *config* Optional configuration values for the checks provider. |
| |
| [[announceUpdate]] |
| == announceUpdate |
| `checksApi.announceUpdate()` |
| |
| Tells Gerrit to call `provider.fetch()`. |
| |
| [[updateResult]] |
| == updateResult |
| `checksApi.updateResult(run: CheckRun, result: CheckResult)` |
| |
| Updates an individual result. This can be used for lazy laoding detailled |
| information. For example, if you are using the |
| link:pg-plugin-endpoints.html#_check_result_expanded[`check-result-expanded` |
| endpoint], then you can load more result details when the user expands a result |
| row. |
| |
| The parameter `run` is only used to *find* the correct run for updating the |
| result. It will only be used for comparing `change`, `patchset`, `attempt` and |
| `checkName`. Its properties other than `results` will not be updated. |
| |
| For us being able to identify the result that you want to update you have to |
| set the `externalId` property. An undefined `externalId` will result in an |
| error. |
| |
| An example usage can be found in link:https://chromium.googlesource.com/infra/gerrit-plugins/buildbucket/+/main/web/checks-result.ts[Chromium Buildbucket Plugin]. |