GitHub Actionsのデバッグに役立つヒントとテクニック

昨日まで正常に動作していたワークフローが、突然不可解なエラーで失敗する。何も変更していないのに。ログには折りたたまれたステップが大量に表示され、その中のどこかに実際の問題が潜んでいる。このシナリオは、CI/CDパイプラインを保守するすべてのエンジニアを悩ませます。

効果的なGitHub Actionsのデバッグには、どのツールが存在し、いつ使用すべきかを知ることが必要です。本ガイドでは、ワークフローの失敗を迅速に診断するための、安定した普遍的なテクニックを紹介します。効果のないアプローチに時間を浪費することなく、問題を解決できます。

より深い可視性のためにデバッグログを有効化する

標準のGitHub Actionsログで十分な詳細が明らかにならない場合は、デバッグログを有効にします。2つのリポジトリシークレットがこの動作を制御します:

• ACTIONS_STEP_DEBUG: trueに設定すると、各ステップの詳細な出力が表示されます
• ACTIONS_RUNNER_DEBUG: trueに設定すると、ランナーレベルの診断情報が表示されます

シークレットを変更せずにデバッグモードをトリガーすることもできます。失敗したワークフローを再実行する際に、「Re-run jobs」を選択し、「Enable debug logging」オプションをチェックします。これにより、今後の実行に影響を与えることなく、その特定の実行の詳細なトレースが提供されます。

GitHubのログビューアは、ライブストリーミングと最近のログの展開表示をサポートしており、長時間実行されるジョブをリアルタイムで追跡しやすくなっています。展開されたステップ内の検索機能を使用して、すべてをスクロールするのではなく、特定のエラーを見つけます。

ワークフローに診断ステップを追加する

カスタムデバッグ情報が必要な場合があります。重要な操作の前に環境詳細を出力するステップを追加します:

- name: Debug environment
  run: |
    echo "Node version: $(node --version)"
    echo "Working directory: $(pwd)"
    echo "Event: ${{ github.event_name }}"
    env | sort

予測不可能に失敗するステップには、一時的にcontinue-on-error: trueを使用します。これにより後続のステップが実行され、失敗が連鎖するのか、それとも分離されたままなのかが明らかになります:

- name: Potentially flaky step
  id: tests
  continue-on-error: true
  run: npm test

- name: Capture state after tests
  if: always()
  run: echo "Tests completed with status ${{ steps.tests.outcome }}"

根本原因を特定したら、continue-on-errorを削除します。

プッシュ前にワークフローをローカルで検証する

ワークフローの構文をテストするためだけにコミットをプッシュするのは、時間の無駄であり、履歴を乱雑にします。actionlintを使用して、GitHubに到達する前にYAMLエラーや式の間違いを検出します:

actionlint .github/workflows/

より包括的なローカルテストには、nektos/actを使用します。これは、GitHubのランナー環境に近いDockerコンテナ内でワークフローを実行します。すべてを再現するわけではありません—アーティファクトの保持期間や正確なソフトウェアバージョンは異なります—が、ステップの実行順序を検証し、明らかな設定問題を検出します。

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

両方のツールは、ワークフローのトラブルシューティングサイクルを大幅に削減する高速なフィードバックループを提供します。

アーティファクトの動作を理解する

GitHub Actionsのアーティファクトはジョブスコープです。v4システムでは、複数のジョブが同じアーティファクト名にアップロードすることはできません—試みるとマージではなく競合が発生します。特にマトリックスビルドや並列ビルドでは、各ジョブに一意のアーティファクト名を付けて、アップロードの失敗を回避し、予測可能な取得を保証します。

再利用可能なワークフローを使用して不安定性を軽減する

リポジトリ間で重複したワークフローロジックは、一貫性の欠如を招きます。同じステップが複数の場所に存在する場合、修正をすべての場所に伝播させる必要があるため、デバッグが困難になります。

再利用可能なワークフローは、共通パターンを一元化します。1か所でバグを修正したり信頼性を向上させたりすると、すべての呼び出し元ワークフローが恩恵を受けます。このアプローチにより、組織全体でCI/CDデバッグを一貫して適用しやすくなります。

アクションのバージョンを固定し、非推奨のアクションを避ける

@mainや@masterではなく、SHAまたは特定のバージョンタグでアクションを参照します。固定されていない参照は、上流の変更が発生したときにワークフローを破損する可能性があります:

# これを推奨
uses: actions/checkout@v4

# これを避ける
uses: actions/checkout@main

多くの古いデバッグヘルパーアクションは、非推奨のNode.jsバージョンを使用しています。GitHubはワークフローログでこれらについて警告します。GitHubが最終的にレガシーランタイムのサポートを削除したときに予期しない失敗を避けるため、メンテナンスされている代替手段に置き換えます。

デバッグ出力でシークレットを保護する

デバッグログはより多くの情報を公開するため、リスクが生じます。デバッグステップであっても、シークレットを直接エコーしないでください。GitHubは既知のシークレットをマスクしますが、派生値や部分一致が漏洩する可能性があります。ログを公開したり、問題レポートで共有したりする前に、デバッグ出力を確認してください。

まとめ

適切なテクニックを知っていれば、ワークフローのトラブルシューティングは管理可能になります。可視性のためにデバッグログを有効にし、戦略的に診断ステップを追加し、actionlintやactでローカルで検証し、再利用可能なワークフローを通じて一貫性を維持します。これらのGitHub Actionsのベストプラクティスは、プラットフォームがどのように進化しても適用されます—これらは、CI/CDデバッグをより速く、より少ないフラストレーションで行うための基本です。

よくある質問

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.