# 必須ステータスチェックのトラブルシューティング

一般的なエラーを解決し、必要な状態チェックをトラブルシューティングして、保護されたブランチへのマージまたはプッシュのブロックを解除します。

必要な状態チェックが、保護されたブランチへのマージまたはプッシュをブロックする場合は、これらのチェックを使用します。 「[Status checks](/ja/pull-requests/reference/status-checks)」を参照してください。

* 過去 7 日間に、選択したリポジトリで必要な状態チェックが正常に完了している必要があります。
* チェックとコミット ステータスが同じ名前である場合、その名前が必須であれば、両方とも成功する必要があります。 「[チェック用 REST API エンドポイント](/ja/rest/checks)」を参照してください。
* ブランチ保護でブランチが最新の状態であることが必要な場合は、ベース ブランチを自分のブランチにマージするか、ベース ブランチ上に自分のブランチをリベースします。 「[保護されたブランチについて](/ja/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging)」と「[Git リベースについて](/ja/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]
> 必須のステータス チェックに合格した最新の pull request は、ローカルでマージされた後で、保護されたブランチにプッシュできます。 これは、マージ コミット自体で状態チェックを実行せずに行うことができます。

## 必要なチェックが最新のコミット SHA に対して成功する必要があります

必要なチェックが引き続きプル要求をブロックしている場合は、次を確認します。

* 必須チェックは最新のコミット SHA で合格している必要があります。 以前のコミットからのチェックは、要件を満たしていません。
* 成功したチェックの状態は、 `success`、 `skipped`、および `neutral`。 「[Status checks](/ja/pull-requests/reference/status-checks)」を参照してください。

## ヘッドコミットとテストマージコミットの間の競合

プル リクエストの状態チェック ボックスを使用して、どのコミットが合格する必要があるかを特定します。

| 状態チェックソース                  | 通過する必要があるもの | 表示される内容                               |
| -------------------------- | ----------- | ------------------------------------- |
| テスト マージ コミットには状態があります      | テストマージコミット  | `Showing checks for the merge commit` |
| テスト用のマージ コミットにはステータスがありません | ヘッド コミット    | 最新のヘッド コミットを確認します                     |

「[Pull request 用 REST API エンドポイント](/ja/rest/pulls/pulls#get-a-pull-request)」を参照してください。

## スキップされた必須チェックの処理

| 原因                                                                                                                                                                                                                                                                                                                                                                  | Result                                  | 修正または確認する方法                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [パス のフィルター処理、分岐のフィルター処理](/ja/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)、[](/ja/actions/reference/workflows-and-actions/workflow-syntax#onpull_requestpull_request_targetbranchesbranches-ignore)または[コミット メッセージ](/ja/actions/how-tos/manage-workflow-runs/skip-workflow-runs)によってワークフローがスキップされる | 関連付けられているチェックは "保留中" 状態のままで、マージをブロックします | スキップできるワークフローを必要としないようにします。                                                                                                                                                   |
| 条件によってジョブがスキップされる                                                                                                                                                                                                                                                                                                                                                   | ジョブが "成功" と報告する                         | 「[条件を使用してジョブの実行を制御する](/ja/actions/how-tos/write-workflows/choose-when-workflows-run/control-jobs-with-conditions)」を参照してください。                                                  |
| ジョブは失敗したジョブに依存する                                                                                                                                                                                                                                                                                                                                                    | 依存ジョブはスキップされ、マージがブロックされない場合があります        | 他のジョブに依存する必要なチェックには、`always()`で`needs`を使用します。 「[ワークフローでジョブを使用する](/ja/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs#defining-prerequisite-jobs)」を参照してください。 |

### Example

このワークフローには正常な `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`が必要な場合、pull request は "状態の報告を待機しています" でブロックされます。

### GitHub Actionsとマージ キューを使用した状態チェック

マージ キューで GitHub Actions チェックが必要な場合は、 `merge_group` イベントを使用してワークフローをトリガーします。

> \[!NOTE]
> リポジトリで GitHub Actions を使用して、リポジトリ内の pull request において必要なチェックを実行する場合は、追加のトリガーとして `merge_group` イベントを含むようにワークフローを更新する必要があります。 それ以外の場合、マージ キューに pull request を追加しても、ステータス チェックがトリガーされません。 必要な状態チェックが報告されないため、マージは失敗します。 `merge_group` イベントは、`pull_request` および `push` イベントとは異なります。

トリガー構成の例:

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

「[ワークフローをトリガーするイベント](/ja/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.
```