This page describes the checker-related REST endpoints that are added by the @PLUGIN@ plugin.
Please also take note of the general information on the REST API.
‘GET /checkers/{checker-id}’
Retrieves a checker.
Note that only users with the Administrate Checkers global capability are permitted to retrieve checkers.
GET /checkers/e1f530851409c89dbba927efd0fbbaf270bfaeae HTTP/1.0
As response a CheckerInfo entity is returned that describes the checker.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"uuid": "e1f530851409c89dbba927efd0fbbaf270bfaeae",
"name": "MyChecker",
"repository": "examples/Foo",
"blocking": [],
"description": "A simple checker.",
"created_on": "2019-01-31 09:59:32.126000000"
}
‘POST /checkers/’
Creates a new checker.
In the request body the data for the checker must be provided as a CheckerInput entity.
Note that only users with the Administrate Checkers global capability are permitted to create checkers.
POST /checkers/ HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"name": "MyChecker",
"description": "A simple checker.",
"repository": "examples/Foo",
}
As response the CheckerInfo entity is returned that describes the created checker.
HTTP/1.1 201 Created
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"uuid": "e1f530851409c89dbba927efd0fbbaf270bfaeae",
"name": "MyChecker",
"description": "A simple checker.",
"repository": "examples/Foo",
"created_on": "2019-01-31 09:59:32.126000000",
"updated_on": "2019-01-31 09:59:32.126000000"
}
‘POST /checkers/{checker-id}’
Updates a checker.
The new property values must be set in the request body in a CheckerInput entity.
This REST endpoint supports partial updates of the checker property set. Only properties that are set in the CheckerInput entity are updated. Properties that are not set in the input (or that have null as value) are not touched.
Unsetting properties:
name: Cannot be unset. Attempting to set it to an empty string ("") or a string that is empty after trim is rejected as 400 Bad Request.description: Can be unset by setting an empty string ("") for it.url: Can be unset by setting an empty string ("") for it.repository: Cannot be unset. Attempting to set it to an empty string ("") or a string that is empty after trim is rejected as 400 Bad Request.status: Cannot be unset.blocking: Can be unset by setting an empty list ([]) for it.Note that only users with the Administrate Checkers global capability are permitted to update checkers.
POST /checkers/e1f530851409c89dbba927efd0fbbaf270bfaeae HTTP/1.0
Content-Type: application/json; charset=UTF-8
{
"description": "A simple checker."
}
As response the CheckerInfo entity is returned that describes the updated checker.
HTTP/1.1 200 OK
Content-Disposition: attachment
Content-Type: application/json; charset=UTF-8
)]}'
{
"uuid": "e1f530851409c89dbba927efd0fbbaf270bfaeae",
"name": "MyChecker",
"description": "A simple checker.",
"repository": "examples/Foo",
"status": "ENABLED",
"created_on": "2019-01-31 09:59:32.126000000",
"updated_on": "2019-02-01 07:23:44.158000000"
}
The UUID of a checker.
Checker names cannot be used as identifier in the REST API since checker names may be ambiguous.
The CheckerInfo entity describes a checker.
| Field Name | Description | |
|---|---|---|
uuid | The UUID of the checker. The checker UUID is generated by Gerrit upon creation of the checker and is immutable. It serves as unique identifier for checkers in the REST API. The checker UUID is URL-safe and doesn't need to be URL encoded for REST calls. | |
name | The name of the checker, may not be unique. | |
description | optional | The description of the checker. |
url | optional | The URL of the checker. |
repository | The (exact) name of the repository for which the checker applies. | |
status | The status of the checker; one of ENABLED or DISABLED. | |
blocking | A list of conditions that describe when the checker should block change submission. | |
created_on | The timestamp of when the checker was created. | |
updated_on | The timestamp of when the checker was last updated. |
The CheckerInput entity contains information for creating a checker.
| Field Name | Description | |
|---|---|---|
name | optional | The name of the checker. Must be specified for checker creation. |
description | optional | The description of the checker. |
url | optional | The URL of the checker. |
repository | optional | The (exact) name of the repository for which the checker applies. |
status | optional | The status of the checker; one of ENABLED or DISABLED. |
blocking | optional | A list of conditions that describe when the checker should block change submission. |
Blocking conditions allow checkers to specify the conditions under which checks will block change submission. The conditions configured for a checker are represented as a list of enum values. When there are multiple blocking conditions, any one of them is sufficient to block submission; in other words, conditions are ORed together.
There is currently only a single type of blocking condition: STATE_NOT_PASSING. Intuitively, if a checker sets this blocking condition, that means that users need to wait for all checks, for example build and test, to pass before submitting the change. In other words, we might say the checker is required.
Technically, STATE_NOT_PASSING requires the combined check state on the change to be either SUCCESSFUL or NOT_RELEVANT.
Part of Gerrit Code Review