{"meta":{"title":"Troubleshooting required status checks","intro":"Resolve common errors and unblock merging or pushing to protected branches by troubleshooting required status checks.","product":"Pull requests","breadcrumbs":[{"href":"/en/pull-requests","title":"Pull requests"},{"href":"/en/pull-requests/how-tos","title":"How-tos"},{"href":"/en/pull-requests/how-tos/merge-and-close-pull-requests","title":"Merge and close"},{"href":"/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks","title":"Troubleshoot status checks"}],"documentType":"article"},"body":"# Troubleshooting required status checks\n\nResolve common errors and unblock merging or pushing to protected branches by troubleshooting required status checks.\n\nUse these checks when a required status check blocks merging or pushing to a protected branch. See [Status checks](/en/pull-requests/reference/status-checks).\n\n* A required status check must have completed successfully in the chosen repository during the past seven days.\n* If a check and a commit status have the same name, both must pass when that name is required. See [REST API endpoints for checks](/en/rest/checks).\n* If branch protection requires your branch to be up-to-date, merge or rebase the base branch into your branch. See [About protected branches](/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) and [About Git rebase](/en/get-started/using-git/about-git-rebase).\n\nIf required status checks have not passed, pushing to a protected branch returns an error similar to this.\n\n```shell\nremote: error: GH006: Protected branch update failed for refs/heads/main.\nremote: error: Required status check \"ci-build\" is failing\n```\n\n> \\[!NOTE]\n> Pull requests that are up-to-date and pass required status checks can be merged locally and pushed to the protected branch. You can do this without running status checks on the merge commit itself.\n\n## Required check needs to succeed against the latest commit SHA\n\nCheck the following if a required check is still blocking a pull request.\n\n* Required checks must pass on the latest commit SHA. Checks from earlier commits don't satisfy the requirement.\n* Successful check statuses are `success`, `skipped`, and `neutral`. See [Status checks](/en/pull-requests/reference/status-checks).\n\n## Conflicts between head commit and test merge commit\n\nUse the pull request status checks box to identify which commit must pass.\n\n| Status check source             | What must pass        | What you may see                      |\n| ------------------------------- | --------------------- | ------------------------------------- |\n| Test merge commit has a status  | The test merge commit | `Showing checks for the merge commit` |\n| Test merge commit has no status | The head commit       | Checks for the latest head commit     |\n\nSee [REST API endpoints for pull requests](/en/rest/pulls/pulls#get-a-pull-request).\n\n## Handling skipped but required checks\n\n| Cause                                                                                                                                                                                                                                                                                                                                                                                       | Result                                                        | How to fix or check                                                                                                                                                                                          |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| A workflow is skipped by [path filtering](/en/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore), [branch filtering](/en/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore), or a [commit message](/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs) | Associated checks stay in a \"Pending\" state and block merging | Avoid requiring workflows that can be skipped.                                                                                                                                                               |\n| A job is skipped by a conditional                                                                                                                                                                                                                                                                                                                                                           | The job reports \"Success\"                                     | See [Using conditions to control job execution](/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions).                                                                 |\n| A job depends on a failed job                                                                                                                                                                                                                                                                                                                                                               | The dependent job is skipped and may not block merging        | Use `always()` with `needs` for required checks that depend on other jobs. See [Using jobs in a workflow](/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs#defining-prerequisite-jobs). |\n\n### Example\n\nThis workflow requires a successful `build` job, but runs only when a pull request changes files in `scripts`.\n\n```yaml\nname: ci\non:\n  pull_request:\n    paths:\n      - 'scripts/**'\njobs:\n  build:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node-version: [12.x, 14.x, 16.x]\n    steps:\n    - uses: actions/checkout@v6\n    - name: Use Node.js ${{ matrix.node-version }}\n      uses: actions/setup-node@v7\n      with:\n        node-version: ${{ matrix.node-version }}\n        cache: 'npm'\n    - run: npm ci\n    - run: npm run build --if-present\n    - run: npm test\n```\n\nA pull request that only changes a file in the repository root will not trigger this workflow. If `build` is required, the pull request is blocked with \"Waiting for status to be reported.\"\n\n### Status checks with GitHub Actions and a Merge queue\n\nIf a merge queue requires a GitHub Actions check, trigger the workflow with the `merge_group` event.\n\n> \\[!NOTE]\n> If your repository uses GitHub Actions to perform required checks on pull requests in your repository, you need to update the workflows to include the `merge_group` event as an additional trigger. Otherwise, status checks will not be triggered when you add a pull request to a merge queue. The merge will fail as the required status check will not be reported. The `merge_group` event is separate from the `pull_request` and `push` events.\n\nExample trigger configuration:\n\n```yaml\non:\n  pull_request:\n  merge_group:\n```\n\nSee [Events that trigger workflows](/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group).\n\n## Required status checks from unexpected sources\n\nA protected branch can also require a status check from a specific GitHub App. If you see a message similar to the following, verify that the check listed in the merge box was set by the expected app.\n\n```text\nRequired status check \"build\" was not set by the expected GitHub App.\n```"}