トラブルシューティングのワークフロー

初期のトラブルシューティングの提案

ワークフロー実行に失敗した場合、トラブルシューティング方法はいくつかあります。

メモ

GitHub Copilot無料サブスクリプションを利用している場合、これは毎月のチャットメッセージ制限にカウントされます。

GitHub Copilot の使用

失敗したワークフロー実行に関する GitHub Copilot とのチャットは、次のいずれかで開くことができます。

失敗したチェックの横にあるマージボックス内のをクリックし、次に Explain errorをクリックします。
マージボックスで、失敗したチェックをクリックします。ワークフロー実行の要約ページの上部にある [ Explain error] をクリックします。

GitHub Copilot とのチャットウィンドウが開き、issue を解決する手順が表示されます。

ワークフロー実行ログの使用

各ワークフローの実行では、表示、検索、ダウンロードできるアクティビティログが生成されます。詳しくは、「ワークフロー実行ログの使用」をご覧ください。

デバッグログを有効にする

ワークフロージョブあるいはステップが期待どおりに動作しない理由を診断する上で、十分な詳細がワークフローのログになかった場合、追加のデバッグロギングを有効化できます。詳しくは、「デバッグログを有効にする」をご覧ください。

ワークフローで特定のツールまたはアクションを使う場合は、デバッグまたは詳細ログオプションを有効にすると、トラブルシューティングのためのより詳細な出力を生成できます。たとえば、npm の場合は npm install --verbose、git の場合は GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ... を使用できます。

請求エラーの精査

Actions の使用には、ランナーの時間 (分) と、ワークフロー成果物のストレージが含まれます。詳しくは、「GitHub Actions の課金」をご覧ください。

予算の設定

Actions の予算を設定すると、課金またはストレージのエラーが原因で失敗したワークフローのブロックをすぐに解除できることがあります。設定した予算額まで、追加の分数とストレージ使用量が課金されます。詳細については、「従量制課金製品の支出を管理するための予算を設定する」を参照してください。

メトリックを使った GitHub Actions アクティビティのレビュー

メトリックを使用してワークフローの効率と信頼性を分析するには、「GitHub Actions メトリックの表示」を参照してください。

ワークフロートリガーのトラブルシューティング

ワークフローの on: フィールドをレビューすることで、ワークフローをトリガーするために想定されることを理解できます。詳しくは、「ワークフローをトリガーする」をご覧ください。

使用できるすべてのイベントの一覧については、「ワークフローをトリガーするイベント」をご覧ください。

発火イベント条件

一部のトリガーイベントは、既定のブランチ (つまり issues、schedule) からのみ実行されます。既定のブランチの外部に存在するワークフローファイルバージョンは、これらのイベントではトリガーされません。

pull request にマージの競合がある場合、pull_request アクティビティではワークフローは実行されません。

コミットメッセージにスキップ注釈が含まれている場合、push または pull_request アクティビティでトリガーされるワークフローはスキップされます。詳しくは、「ワークフロー実行をスキップする」をご覧ください。

予期しない時間に実行されるスケジュールされたワークフロー

スケジュールされたイベントは、GitHub Actions ワークフローの実行によって高い負荷がかかっている間は遅延される可能性があります。

高負荷時間には、毎時の初めが含まれます。負荷が十分に高い場合、キューに登録されたジョブの一部が削除される可能性があります。遅延の可能性を減らすために、Ⅰ時間の中の別の時間帯に実行されるようワークフローをスケジューリングしてください。詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

フィルター処理と差分の制限

一部のイベントでは、カスタマイズ可能なブランチ、タグ、パスによるフィルター処理が可能です。フィルター条件が適用されてワークフローがフィルターで除外される場合、ワークフロー実行の作成はスキップされます。

フィルターには特殊文字を使用できます。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

パスフィルター処理の場合、差分の評価は最初の 300 ファイルに制限されます。フィルターによって返される最初の 300 ファイルと一致しないファイルが変更された場合、ワークフローは実行されません。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

ワークフロー実行のトラブルシューティング

ワークフロー実行には、ワークフローがトリガーされ、ワークフロー実行が作成された後に発生したすべての issue が含まれます。

ジョブ条件のデバッグ

ジョブが予期せずスキップされた場合、またはスキップされることが予想されたときに実行された場合は、式の評価を表示して、その理由を理解できます。

ワークフロー実行でジョブをクリックします。
ジョブのメニューからログアーカイブをダウンロードします。

       `JOB-NAME/system.txt` ファイルを開きます。

       `Evaluating`、`Expanded`、および`Result`行を探します。

       `Expanded`行には、`if`条件に置き換えられた実際のランタイム値が表示され、式が`true`または`false`に評価された理由が明確になります。

詳しくは、「ジョブ条件式ログの表示」をご覧ください。

ワークフローの取り消し

          [UI](/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/canceling-a-workflow) または [API](/rest/actions/workflow-runs?apiVersion=2022-11-28#cancel-a-workflow-run) による標準の取り消しが期待どおりに処理されない場合は、実行中のワークフロー ジョブに対して取り消されない条件付きステートメントが構成されている可能性があります。

このような場合、API を利用して実行を強制的に取り消すことができます。詳しくは、「ワークフロー実行の REST API エンドポイント」をご覧ください。

原因のひとつとして、ステータスチェック機能が取り消し時でもを返す場合が考えられます。 cancelled() 関数の逆関数である ${{ !cancelled() }} を使う方法もあります。

詳細については、「条件を使用してジョブの実行を制御する」および「ワークフローの実行をキャンセルする」を参照してください。

ランナーの問題解決

ランナーラベルを定義する

GitHub-ホステッドランナーは、を、で管理される形で活用します。

大規模なセルフホステッドランナーには、一意のラベル名を使うことをお勧めします。ラベルが既存のプリセットラベルのいずれかと一致する場合、どの一致するランナーオプションでジョブが実行されるかが保証されず、ランナーの割り当てに関する issue が発生する可能性があります。

セルフホステッドランナー

セルフホストランナーを使用する場合、そのアクティビティを見て、一般的な問題を診断できます。

詳しくは、「自己ホストランナーのモニタリングとトラブルシューティング」をご覧ください。

ネットワークのトラブルシューティングの提案

以下のネットワークの問題については、サポートが限定されます。

あなたのネットワーク
外部ネットワーク
サードパーティ製システム
一般的なインターネット接続

GitHub のリアルタイムプラットフォーム状態を表示するには、「GitHub の状態」をチェックします。

その他のネットワーク関連の問題については、organization のネットワーク設定をレビューし、アクセスしているサードパーティサービスの状態をレビューします。問題が解決しない場合は、ネットワーク管理者に連絡してサポートを受けることを検討してください。

問題について不明な点がある場合は、GitHub のサポートにお問い合わせください。サポートへの連絡方法の詳細については、「GitHub Support へのお問い合わせ」を参照してください。

DNS

ドメインネームシステム (DNS) の構成、解決、またはリゾルバーの問題が原因で問題が発生する可能性があります。使用できるログやベンダーのドキュメントをレビューするか、管理者に問い合わせて追加のサポートを受けることをお勧めします。

ファイアウォール

ファイアウォールによってアクティビティが禁止される可能性があります。このような問題が発生した場合は、使用できるログやベンダーのドキュメントをレビューするか、管理者に問い合わせて追加のサポートを受けることをお勧めします。

プロキシ

通信にプロキシを使うとアクティビティが失敗する可能性があります。使用できるログやベンダーのドキュメントをレビューするか、管理者に問い合わせて追加のサポートを受けることをお勧めします。

プロキシを利用するためのランナーアプリケーションの構成については、「ランナーでのプロキシサーバの使用」を参照してください。

サブネット

仮想クラウドプロバイダーや Docker ネットワーク内など、使用中のサブネットや既存のネットワークとの重複により問題が発生する可能性があります。このような場合は、ネットワークトポロジと使用中のサブネットをレビューすることをお勧めします。

証明書

自己署名またはカスタムの証明書チェーンおよび証明書ストアが原因で問題が発生する可能性があります。使用中の証明書の有効期限が切れておらず、現在信頼されているかどうかをチェックできます。証明書は curl または同様のツールを使って検査できます。使用できるログやベンダーのドキュメントをレビューするか、管理者に問い合わせて追加のサポートを受けることもできます。

IP リスト

IP 許可リストまたは拒否リストにより、想定される通信が中断される可能性があります。問題がある場合は、使用できるログやベンダーのドキュメントをレビューするか、管理者に問い合わせて追加のサポートを受ける必要があります。

GitHub によってホストされるランナーで使用されるものなど、GitHub の IP アドレスに関する情報は、「GitHubの IP アドレスについて」をご覧ください。

静的 IP アドレスは、GitHub によるホステッドの大型ランナーで使用できます。詳細については、「より大きなランナーを管理する」を参照してください。

オペレーティングシステムとソフトウェアアプリケーション

ファイアウォールやプロキシに加えて、追加のソフトウェアパッケージのインストールなど、GitHub ホステッドランナーに対するカスタマイズの実行によって、通信が中断される可能性があります。使用できるカスタマイズオプションの詳細については、「GitHubホストランナーのカスタマイズ」を参照してください。

セルフホステッドランナーの場合は、「セルフホステッドランナーリファレンス」で必要なエンドポイントの詳細を確認します。
WireGuard の構成については、「WireGuard を使用してネットワークオーバーレイを作成する」を参照してください。
OpenID Connect (OIDC) の構成の詳細については、「OIDC とともに API ゲートウェイを使用する」を参照してください。

GitHub ホステッドランナー向けの Azure プライベートネットワーク

構成された Azure 仮想ネットワーク (VNET) 設定内で GitHub ホステッドランナーを使うと、問題が発生する可能性があります。

トラブルシューティングのアドバイスについては、「組織内の GitHub ホストランナーの Azure プライベートネットワーク設定のトラブルシューティング」またはGitHub Enterprise Cloud ドキュメントの「GitHubホストランナー向けの企業内Azureプライベートネットワーク構成のトラブルシューティング」を参照してください。

トラブルシューティングのワークフロー

この記事で