GitHub Checks API Enables Apps for Advanced Continuous Integration

GitHub Checks API aims to make it possible to integrate code checks into a continuous integration workflow. For example this could mean linting a source file and present the results directly in the pull request view. The feedback can be as detailed as desired, e.g., showing the line of code causing a problem, thus allowing the commit author to fix the issues and run a new check on the code.

The GitHub Checks API can be regarded as an evolution of the traditional GitHub status API, which allows external services to mark commits with a status code, i.e. fail or pass, which is reflected in pull requests involving those commits. Using the Checks API, integrators have now more fine-grained control over the status of a commit or PR, including success, failure, neutral, cancelled, timed_out, or action_required, as well as queued, in_progress, or completed. Additionally, a check can include a variety of data, such as textual information, images, etc. This allows to build sophisticated workflows where you have a number of checks run against a commit or PR, and GitHub will show you which ones pass and which ones fail and which require attention.

GitHub supports various levels of controls of checks workflows:

• Automatic: all installed applications with the checks:write permission will be sent events for them to start analyzing the changes. All apps running checks are listed by the GitHub UI, so the integrator and developer can monitor how the checks progress and take action if required
• User: a specific check can be requested through a request like: POST /repos/:owner/:repo/check-suite-requests or by adding skip-checks: true or request-checks: true directives to a commit message
• Web UI: users can run checks, either individually or all of them, using GitHub Web UI

For a GitHub App to be able to run checks, it must handle check_suite webhooks, which specify the requested actions. The app can then create a new check run that GitHub will add to the check suite for that app, which summarizes all of its checks and outcomes. An app will initially create a check run in the queued or in progress state and then will update it as it progresses. To work out all the details of the messages that apps and GitHub need to exchange, refer to the previously mentioned documentation.

Currently, the GitHub Checks API only works with GitHub REST API, while support for checks in the GraphQL API is in the workings.