Required status checks ensure that all required CI tests are passing before collaborators can make changes to a protected branch.

If you've enforced branch protections in your repository, you can set up required status checks. For more information, see "Configuring protected branches" and "Enabling required status checks." Required status checks can be checks or statuses. For more information, see "About status checks."

After enabling required status checks, all required status checks must pass before branches can be merged into the protected branch. Any commits must either be pushed to another branch and then merged or pushed directly to the protected branch, after all required status checks have passed.

Merge protected branch

If you have a check and a status with the same name and you select that name as a required status check, both the check and the status will be required. For more information, see "Checks" in the GitHub Developer documentation.

Once you've set up required status checks, your branch must be up to date with the base branch before merging. This ensures that your branch has been tested with the latest code from the base branch. If your branch is out of date, you'll need to merge the base branch into your branch.

Note: You can also bring your branch up to date with the base branch by using Git rebase.

Out-of-date branch

You won't be able to push local changes to a protected branch until all required status checks pass. Instead, you'll receive an error message similar to the following:

remote: error: GH006: Protected branch update failed for refs/heads/master.
remote: error: Required status check "ci-build" is failing

Note: Pull requests that are up to date and pass required status checks can be merged locally and pushed to the protected branch. This can be done without status checks running on the merge commit itself.

Administrators of a repository can merge a protected branch even if required status checks have failed or are pending. You can require administrators to be subject to required status checks.

Administrator merge of protected branch

Administrators can also merge a protected branch even if the branch is out of date with the base branch.

You can set up either loose or strict status checks, depending on whether you want to require your branch to be up to date with the base branch before merging.

Further reading