Status checks let you know if your commits meet the conditions set for the repository you're contributing to.

Status checks are based on external processes, such as continuous integration builds, which run for each push you make to a repository. You can see the pending, passing, or failing state of status checks next to individual commits in your pull request.

List of commits and statuses

You can see the overall state of the last commit to a branch on your repository's branches page or in your repository's list of pull requests.

If status checks are required for a repository, the required status checks must pass before you can merge your branch into the protected branch. For more information, see "About required status checks."

Checks

Note: Checks are currently in public beta and are only available for use with GitHub Apps.

Checks and statuses are the two types of status checks on GitHub. Checks are different from statuses in that they provide line annotations, more detailed messaging, and are only available for use with GitHub Apps.

Organization owners and users with push access to a repository can create checks and statuses with GitHub's API. For more information, see "Checks" and "Statuses" in the GitHub Developer documentation.

When you set up checks for a repository, in addition to the other status check functionality, you can view detailed build output from status checks in the Checks tab of a pull request and rerun failed checks.

Status checks within a pull request

When a specific line in a commit causes a check to fail, you will see details about the failure, warning, or notice next to the relevant code in the Files tab of the pull request.

Details of failed status check

Skipping and requesting checks for individual commits

When a repository is set to automatically request checks for pushes, you can choose to skip checks for an individual commit you push. When a repository is not set to automatically request checks for pushes, you can request checks for an individual commit you push. For more information on these settings, see "Check Suites" in the GitHub Developer documentation.

To skip or request checks for your commit, add one of the following trailer lines to the end of your commit message:

  • To skip checks for a commit, type your commit message and a short, meaningful description of your changes. After your commit description, instead of a closing quotation, add two empty lines followed by skip-checks: true:

    git commit -m "Update README.
    >
    >
    skip-checks: true
    
  • To request checks for a commit, type your commit message and a short, meaningful description of your changes. After your commit description, instead of a closing quotation, add two empty lines followed by request-checks: true:

    git commit -m "Refactor usability tests.
    >
    >
    request-checks: true