Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
All products
Repositories

This version of GitHub Enterprise was discontinued on 2023-03-15. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Troubleshooting required status checks

In this article

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

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and 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."

Handling skipped but required checks

Note: If a workflow is skipped due to path filtering, branch filtering or a commit message, then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging.

If a job in a workflow is skipped due to a conditional, it will report its status as "Success". For more information see Skipping workflow runs and Using conditions to control job execution.

Example

The following example shows a workflow that requires a "Successful" completion status for the build job, but the workflow will be skipped if the pull request does not change any files in the scripts directory.

name: ci
on:
  pull_request:
    paths:
      - 'scripts/**'
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [12.x, 14.x, 16.x]
    steps:
    - uses: actions/checkout@v2
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v2
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

Due to path filtering, a pull request that only changes a file in the root of the repository will not trigger this workflow and is blocked from merging. On the pull request, you would see "Waiting for status to be reported."

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
on:
  pull_request:
    paths-ignore:
      - 'scripts/**'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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.

Notes:

  • 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.

Required status checks from unexpected sources

It's also possible for a protected branch to require a status check from a specific GitHub App. 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 App.