Using the REST API to interact with checks

You can use the REST API to build GitHub Apps that run powerful checks against code changes in a repository. You can create apps that perform continuous integration, code linting, or code scanning services and provide detailed feedback on commits.

In this article

Overview

Rather than binary pass/fail build statuses, GitHub Apps can report rich statuses, annotate lines of code with detailed information, and re-run tests. REST API to manage checks is available exclusively to your GitHub Apps.

For an example of how to use the REST API with a GitHub App, see Building CI checks with a GitHub App.

You can use statuses with protected branches to prevent people from merging pull requests prematurely. For more information, see About protected branches.

About check suites

When someone pushes code to a repository, GitHub creates a check suite for the last commit. A check suite is a collection of the check runs created by a single GitHub App for a specific commit. Check suites summarize the status and conclusion of the check runs that a suite includes.

The status can be queued, in_progress, requested, waiting, pending, or completed. Only GitHub Actions can set a status of requested, waiting, or pending.

If the status is completed, the conclusion can be any of the following:

  • action_required
  • cancelled
  • timed_out
  • failure
  • neutral
  • skipped
  • stale
  • startup_failure
  • success

The check suite reports the highest priority check run conclusion in the check suite's conclusion. For example, if three check runs have conclusions of timed_out, success, and neutral the check suite conclusion will be timed_out.

By default, GitHub creates a check suite automatically when code is pushed to the repository. This default flow sends the check_suite event (with requested action) to all GitHub Apps that have the checks:write permission. When your GitHub App receives the check_suite event, it can create new check runs for the latest commit. GitHub automatically adds new check runs to the correct check suite based on the check run's repository and SHA.

If you don't want to use the default automatic flow, you can control when you create check suites. To change the default settings for the creation of check suites, use the Update repository preferences for check suites endpoint. All changes to the automatic flow settings are recorded in the audit log for the repository. If you have disabled the automatic flow, you can create a check suite using the Create a check suite endpoint. You should continue to use the Create a check run endpoint to provide feedback on a commit.

Write permission for the REST API to interact with checks is only available to GitHub Apps. OAuth apps and authenticated users can view check runs and check suites, but they are not able to create them. If you aren't building a GitHub App, you might be interested in using the REST API to interact with commit statuses.

To use the endpoints to manage check suites, the GitHub App must have the checks:write permission and can also subscribe to the check_suite webhook.