@PLUGIN@ - /checkers/ REST API

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.

Checker Endpoints

Get Checker

‘GET /checkers/{checker-id}

Retrieves a checker.

Note that only users with the Administrate Checkers global capability are permitted to retrieve checkers.

Request

  GET /checkers/e1f530851409c89dbba927efd0fbbaf270bfaeae HTTP/1.0

As response a CheckerInfo entity is returned that describes the checker.

Response

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8
  )]}'
  {
    "uuid": "test:my-checker",
    "name": "MyChecker",
    "repository": "examples/Foo",
    "blocking": [],
    "description": "A simple checker.",
    "created_on": "2019-01-31 09:59:32.126000000"
  }

Create Checker

‘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.

Request

  POST /checkers/ HTTP/1.0
  Content-Type: application/json; charset=UTF-8
  {
    "uuid": "test:my-checker",
    "name": "MyChecker",
    "description": "A simple checker.",
    "repository": "examples/Foo",
  }

As response the CheckerInfo entity is returned that describes the created checker.

Response

  HTTP/1.1 201 Created
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8
  )]}'
  {
    "uuid": "test:my-checker",
    "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"
  }

Update Checker

‘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:

  • uuid: Cannot be unset or otherwise modified.
  • name: Can be unset by setting an empty string ("") for it.
  • 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.
  • query: Can be unset by setting an empty string ("") for it. Note that the default for newly-created checkers is not empty; see below.

Note that only users with the Administrate Checkers global capability are permitted to update checkers.

Request

  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.

Response

  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8
  )]}'
  {
    "uuid": "test:my-checker",
    "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"
  }

IDs

{checker-id}

The UUID of a checker.

UUIDs are of the form SCHEME ':' ID. The scheme and ID portions may only contain alphanumeric characters (a-z, A-Z, 0-9) plus the punctuation characters ., _, and -. Thus UUIDs are URL-safe without escaping.

The scheme is by convention a short string (max 100 chars) associated with the external system that created the checker, for example jenkins. The scheme must also be a valid ref name component according to git-check-ref-format, for example it may not start or end with a period.

The ID is an arbitrary identifier that may have meaning to the external system.

UUIDs must be unique and are immutable after creation.

Checker names cannot be used as identifiers in the REST API since checker names may be ambiguous.

JSON Entities

CheckerInfo

The CheckerInfo entity describes a checker.

Field NameDescription
uuidThe UUID of the checker.
nameThe name of the checker, may not be unique.
descriptionoptionalThe description of the checker.
urloptionalThe URL of the checker.
repositoryThe (exact) name of the repository for which the checker applies.
statusThe status of the checker; one of ENABLED or DISABLED.
blockingA list of conditions that describe when the checker should block change submission.
queryoptionalA query that limits changes for which the checker is relevant.
created_onThe timestamp of when the checker was created.
updated_onThe timestamp of when the checker was last updated.

CheckerInput

The CheckerInput entity contains information for creating a checker.

Field NameDescription
nameoptionalThe name of the checker. Must be specified for checker creation.
descriptionoptionalThe description of the checker.
urloptionalThe URL of the checker.
repositoryoptionalThe (exact) name of the repository for which the checker applies.
statusoptionalThe status of the checker; one of ENABLED or DISABLED.
blockingoptionalA list of conditions that describe when the checker should block change submission.
queryoptionalA query that limits changes for which the checker is relevant.

Blocking Conditions

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, WARNING, or NOT_RELEVANT.

Query

If the query field is specified in the checker config, then the checker is only considered relevant for changes matching that query. The query field is interpreted as a change query, with a limited subset of supported operators. By default, the query for newly-created checkers is status:open. An empty query matches all changes.

In order to determine the relevant checkers for a given change, Gerrit first looks up all enabled checkers matching that change's repository, then executes the query for each checker in sequence. Because of this algorithm, there are restrictions on which operators can be supported in checker queries:

  • Operators related to projects are not supported, since the algorithm already only considers checkers with a matching repository.
  • Full-text operators (e.g. message) are not supported, since these cannot be efficiently evaluated sequentially.
  • Operators with an explicit or implied self user are not supported, since the algorithm must return the same set of relevant checkers regardless of the end user looking at the change.

Currently, the set of allowed query operators is:

added, after, age, assignee, author, before, branch, committer, deleted, delta, destination, dir, directory, ext, extension, f, file, footer, hashtag, intopic, label, onlyextensions, onlyexts, ownerin, path, r, ref, reviewer, reviewerin, size, status, submittable, topic, unresolved, wip


Part of Gerrit Code Review