Troubleshooting required status checks

You can check for common errors and resolve issues with required status checks.

受保护分支适用于具有 GitHub Free 和组织的 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。

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 are required. For more information, see "Checks."

After you enable required status checks, your branch may need to 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. For more information, see "About protected branches."

Note: You can also bring your branch up to date with the base branch using Git rebase. For more information, see "About 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/main.
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.

Conflicts between head commit and test merge commit

Sometimes, the results of the status checks for the test merge commit and head commit will conflict. If the test merge commit has a status, the test merge commit must pass. Otherwise, the status of the head commit must pass before you can merge the branch. For more information about test merge commits, see "Pulls."

Branch with conflicting merge commits

Handling skipped but required checks

Sometimes a required status check is skipped on pull requests due to path filtering. For example, a Node.JS test will be skipped on a pull request that just fixes a typo in your README file and makes no changes to the JavaScript and TypeScript files in the scripts directory.

If this check is required and it gets skipped, then the check's status is shown as pending, because it's required. In this situation you won't be able to merge the pull request.


In this example you have a workflow that's required to pass.

name: ci
      - 'scripts/**'
      - 'middleware/**'
    runs-on: ubuntu-latest
        node-version: [12.x, 14.x, 16.x]
    - uses: actions/checkout@v2
    - name: Use Node.js $
      uses: actions/setup-node@v2
        node-version: $
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

If someone submits a pull request that changes a markdown file in the root of the repository, then the workflow above won't run at all because of the path filtering. As a result you won't be able to merge the pull request. You would see the following status on the pull request:

Required check skipped but shown as pending

You can fix this by creating a generic workflow, with the same name, that will return true in any case similar to the workflow below :

name: ci
      - 'scripts/**'
      - 'middleware/**'
    runs-on: ubuntu-latest
      - run: 'echo "No build required" '

Now the checks will always pass whenever someone sends a pull request that doesn't change the files listed under paths in the first workflow.

Check skipped but passes due to generic workflow


  • Make sure that the name key and required job name in both the workflow files are the same. For more information, see "Workflow syntax for GitHub Actions".
  • The example above uses GitHub Actions but this workaround is also applicable to other CI/CD providers that integrate with GitHub.

It's also possible for a protected branch to require a status check from a specific GitHub 应用程序. If you see a message similar to the following, then you should verify that the check listed in the merge box was set by the expected app.

Required status check "build" was not set by the expected GitHub 应用程序.




所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。


或者, 了解如何参与。