Skip to main content

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

ステータスチェック必須を使用して、一般的なエラーを調べ、問題を解決できます。

この機能を使用できるユーザーについて

保護されたブランチは、組織の GitHub Free と GitHub Free のパブリック リポジトリで使用できます。 保護されたブランチは、GitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server のパブリック リポジトリとプライベート リポジトリでも使用できます。詳しくは、「GitHub のプラン」をご覧ください。

同じ名前のチェックとステータスがあり、その名前をステータスチェック必須とするようにした場合、チェックとステータスはどちらも必須になります。 詳しくは、「チェック用 REST API エンドポイント」を参照してください。

注: 必須にするには、ステータス チェックが過去 7 日間に選択したリポジトリ内で正常に完了している必要があります。

ステータスチェック必須を有効にした後、マージする前にブランチをベースブランチに対して最新にする必要がある場合があります。 これによって、ブランチがベースブランチからの最新のコードでテストされたことが保証されます。 ブランチが古い場合、ベースブランチをブランチにマージする必要があります。 詳しくは、「保護されたブランチについて」を参照してください。

注: Git リベースを使用してブランチをベース ブランチと同じ最新状態にすることもできます。 詳しくは、「Git リベースについて」を参照してください。

必須ステータスチェックにすべてパスするまでは、ローカルでの変更を保護されたブランチにプッシュすることはできません。 その代わりに、以下のようなエラー メッセージが返されます。

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

注: 必須状態チェックに合格した最新の pull request は、ローカルでマージされた後で、保護されたブランチにプッシュできます。 これはマージコミット自体でステータスチェックを実行せずに行えます。

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

Pull request をマージするには、必要なすべてのチェックが最新のコミット SHA に対して成功する必要があります。 これにより、マージする前に、最新加えられた変更が検証され、必要な標準を満たしていることが保証されます。 以前のコミット SHA を使用してトリガーされたチェックは、必要なチェックの一部として使用されません。

head コミットとテスト マージ コミットの間の競合

テストマージコミットと head コミットのステータスチェックの結果が競合する場合があります。 テストマージコミットにステータスがある場合、そのテストマージコミットは必ずパスする必要があります。 それ以外の場合、ヘッドコミットのステータスは、ブランチをマージする前にパスする必要があります。

テスト マージ コミットとヘッド コミットの間に競合がある場合は、テスト マージ コミットのチェックが pull request ステータス チェック ボックスに表示されます。 これは、pull request 状態ボックスに Showing checks for the merge commit で始まる行で示されます。 テスト マージ コミットの詳細については、「Pull request 用 REST API エンドポイント」を参照してください。

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

警告: パス フィルターブランチ フィルター、またはコミット メッセージのためにワークフローがスキップされた場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

ただし、ワークフロー内のジョブが条件付きのためにスキップされた場合、状態は "成功" として報告されます。 詳しくは、「条件を使用してジョブの実行を制御する」を参照してください。

ジョブが失敗すると、失敗したジョブに依存するすべてのジョブはスキップされ、エラーは報告されません。 チェックを必要とする pull request はブロックされない可能性があります。 他のジョブに依存するジョブで必要なチェックを使用するには、needs に加えて always() 条件式を使用します。「ワークフローでジョブを使用する」を参照してください。

次の例で示すのは、build ジョブの完了状態が "成功" であることが必要なワークフローです。ただし、pull request が scripts ディレクトリのどのファイルも変更しないと、このワークフローはスキップされます。

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@v4
    - 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

パスのフィルター処理のために、リポジトリのルートのファイルのみを変更する pull request は、このワークフローをトリガーせず、マージがブロックされます。 pull request には、"状態の報告を待機しています" と表示されます。

GitHub Actions とマージ キューによるステータス チェック

pull request がマージ キューに追加されたときに GitHub Actions ワークフローをトリガーするには、merge_group イベントを使用する必要があります

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

ターゲット ブランチの保護で必要なチェックを報告するワークフローは、次のようになります。

on:
  pull_request:
  merge_group:

merge_group イベントの詳細については、「ワークフローをトリガーするイベント」をご覧ください。

予期しないソースからの必要な状態チェック

保護されたブランチで、特定の GitHub App の状態チェックを必須にすることもできます。 次のようなメッセージが表示された場合は、マージ ボックスに一覧表示されているチェックが、想定されるアプリによって設定されたことを確認する必要があります。

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