The Checks API allows you to display external statuses in deployment requests. Each check has an error, failure, pending, or success state, which is shown in the app.


You can configure status checks as required for a branch. Those required status checks must pass before your teammates can deploy their changes. For more information, see "About required status checks."

Reporting external statuses

Status checks have a name to indicate what service is reporting that status. For example, a continuous integration service pushes statuses with a name of "ci", while a security audit tool uses "security".

The check has a state that shows whether it is queued, in progress, or done. You can start with any initial state, so a check can be initially marked as done, if you already know the outcome. Done checks must report a result, such as success, failure, or skipped.

Statuses can also include a description and externalUrl, for more information. As an example, one common use is for continuous integration services to mark commits as passing or failing builds using status. The externalUrl would be the full URL to the build output, and the description would be the high level summary of what happened with the build.