About required status checks
Required status checks ensure that all required CI tests are passing before collaborators can make changes to a protected branch.
Protected branches are available in public repositories with GitHub Free, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see "GitHub's products."
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.
Note: Any person or integration with write permissions to a repository can set the state of any status check in the repository. GitHub does not verify that the author of a check is authorized to create a check with a certain name or modify an existing status. You should verify that the author of each status, listed in the merge box, is expected before merging a pull request.
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.
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.
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.