# 必需状态检查故障排除

通过排查必需的状态检查，解决常见错误，并解除合并或推送到受保护分支时的阻碍。

当所需的状态检查阻止合并或推送到受保护的分支时，请使用这些检查。 请参阅“[Status checks](/zh/pull-requests/reference/status-checks)”。

* 在过去七天内，必须在所选存储库中成功完成所需的状态检查。
* 如果检查和提交状态具有相同的名称，则当该名称为必需时，两者都必须通过。 请参阅“[检验的 REST API 端点](/zh/rest/checks)”。
* 如果分支保护要求您的分支保持最新，请将基分支合并到您的分支中，或将您的分支变基到基分支之上。 请参阅 [关于受保护分支](/zh/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) 和 [关于 Git 变基](/zh/get-started/using-git/about-git-rebase)。

如果所需的状态检查尚未通过，推送到受保护分支时会返回类似如下的错误。

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

> \[!NOTE]
> 保持最新且通过必需状态检查的拉取请求可以在本地合并并推送到受保护分支。 可以在不对合并提交本身运行状态检查的情况下执行此操作。

## 必要的检查必须在最新提交的 SHA 上成功通过

如果某项必需检查仍在阻止拉取请求，请检查以下各项。

* 必需检查必须在最新提交的 SHA 上通过。 早期提交中的检查结果未满足要求。
* 成功的检查状态为 `success`， `skipped`以及 `neutral`。 请参阅“[Status checks](/zh/pull-requests/reference/status-checks)”。

## 头部提交与测试合并提交之间的冲突

使用拉取请求状态检查框来确定哪个提交必须通过状态检查。

| 状态检查来源       | 必须通过的项目 | 你可能会看到的内容                             |
| ------------ | ------- | ------------------------------------- |
| 测试合并提交具有状态   | 测试合并提交  | `Showing checks for the merge commit` |
| 测试合并提交没有状态信息 | 头提交     | 检查最新的 HEAD 提交                         |

请参阅“[用于拉取请求的 REST API 终结点](/zh/rest/pulls/pulls#get-a-pull-request)”。

## 处理被跳过但仍需完成的检查

| 原因                                                                                                                                                                                                                                                                                                                                 | Result                 | 如何修复或检查                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 通过[路径筛选](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)、[分支筛选](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore)或[提交消息](/zh/actions/how-tos/manage-workflow-runs/skip-workflow-runs)跳过工作流 | 关联的检查始终处于“挂起”状态，导致无法合并 | 避免需要可以跳过的工作流。                                                                                                                                                     |
| 作业因条件判断而被跳过                                                                                                                                                                                                                                                                                                                        | 作业报告“成功”               | 请参阅“[使用条件控制作业执行](/zh/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions)”。                                                    |
| 一个任务依赖于失败的任务                                                                                                                                                                                                                                                                                                                       | 依赖作业已被跳过，且可能不会阻止合并     | 将 `always()` 与 `needs` 配合使用，以满足依赖于其他作业的必需检查。 请参阅“[在工作流程中使用任务](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs#defining-prerequisite-jobs)”。 |

### 示例

此工作流需要一个成功完成的 `build` 作业，但仅在拉取请求更改了 `scripts` 中的文件时才会运行。

```yaml
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@v6
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test
```

仅更改存储库根目录中的文件的拉取请求不会触发此工作流。 如果需要 `build`，拉取请求会被阻止，并显示“正在等待状态上报。”

### 使用 GitHub Actions 和合并队列的状态检查

如果合并队列要求进行 GitHub Actions 检查，请使用 `merge_group` 事件触发工作流。

> \[!NOTE]
> 如果存储库使用 GitHub Actions 执行所需检查 要求工作流，则需要更新工作流以包含 `merge_group` 事件作为其他触发器。 否则在将拉取请求添加到合并队列时不会触发状态检查。 合并将失败，因为没有报告必要的状态检查。 事件 `merge_group` 独立于 `pull_request` 和 `push` 事件。

示例触发器配置：

```yaml
on:
  pull_request:
  merge_group:
```

请参阅“[触发工作流的事件](/zh/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group)”。

## 要求从意外源进行状态检查

受保护的分支还可以要求从特定 GitHub App分支进行状态检查。 如果看到类似于以下内容的消息，请验证合并框中列出的复选框是否已由预期的应用设置。

```text
Required status check "build" was not set by the expected GitHub App.
```