GitHub Actions でワークフローを管理およびデバッグする

  • 10 分

開発者がコード ベースに変更を追加するたびに機能が更新されるように、コードのビルドと発行プロセスを自動化することが目的であることを思い出してください。

このプロセスを実装するには、次の方法を学習します。

  • ワークフローをトリガーしたイベントを特定します。
  • GitHub Actions ワークフロー ログを使用します。
  • ビルド成果物を保存してアクセスします。
  • レビュー後にプル要求へのラベルの追加を自動化します。

ワークフローをトリガーしたイベントを特定する

GITHub Actions ワークフローをトリガーした理由を理解することは、CI/CD パイプラインのデバッグ、監査、および改善に不可欠です。 トリガーの種類には、ブランチへのプッシュ、作成または更新されたプル要求、スケジュールされたジョブ、手動ディスパッチが含まれます。 トリガー イベントは、ワークフローの実行、リポジトリの変更、および関連する GitHub の問題またはプル要求を調べることで識別できます。

プッシュ、プル要求、スケジュール、手動ディスパッチなど、GitHub Actions のさまざまなワークフロー トリガーを示す図。

ワークフロー トリガーとは

ワークフロー トリガーは、ワークフローを実行させるイベントです。 GitHub では、次のようなさまざまな種類のトリガーがサポートされています。

  • push または pull_request (コードの変更に基づく)
  • workflow_dispatch (手動トリガー)
  • schedule (cron ジョブ)
  • repository_dispatch (外部システム)
  • 問題、ディスカッション、pull request イベント ( issues.opened、 pull_request.closedなど)

トリガー イベントを識別する

ワークフロー トリガー イベントは、次の複数の方法で識別できます。

  • GitHub Actions UI を使用します。

    1. リポジトリで、[ アクション] タブを選択します。
    2. ワークフロー実行を選択します。

    ワークフロー実行の概要の上部に、 push、 pull_request、 workflow_dispatchなどのイベントの種類が表示されます。

  • ログまたはワークフローで github.event_name を使用します。

    • GitHub は、ワークフローの実行中にコンテキスト データを公開します。 github.event_name変数は、ワークフローをトリガーしたイベントを示します。

    • デバッグの手順で情報を出力できます。

      -name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"

  • ワークフローの実行詳細を使う。

    • API を使用するなど、プログラムによってワークフローの実行を検査する場合、実行オブジェクトにはトリガーを指定する event プロパティが含まれます。
    • コミット セキュア ハッシュ アルゴリズム (SHA)、アクター、タイムスタンプを見つけて、トリガーの原因をトレースできます。

リポジトリの効果からトリガーを推論する

ワークフロー実行に直接アクセスできない場合もありますが、リポジトリ アクティビティに基づいてワークフロー実行をトリガーした原因を推測する必要があります。

観察された動作 トリガー イベント
新しいコミットが main にプッシュされ、ワークフローが実行されました。 push 出来事
pull request が開かれました、または更新されました。 pull_request 出来事
共同作成者がワークフローを手動で実行しました。 workflow_dispatch
ワークフローは、特定の時刻に毎日実行されます。 schedule（cron）
ワークフローは、外部サービス呼び出しの後に実行されました。 repository_dispatch
ワークフローは、問題にラベルまたはコメントが追加されたときに実行されました。 issues.* 出来事

タイムスタンプ、プル要求アクティビティ、コミット履歴を確認することで、ワークフローの実行原因となったアクションを特定できることがよくあります。

ワークフローをトリガーした原因を特定する方法を要約するには:

  • [アクション] タブでワークフロー実行の概要を確認します。
  • ワークフロー内の github.event_name を印刷またはログに記録して表示します。
  • タイムスタンプとリポジトリ アクティビティ (コミット、プル要求、問題) を比較して、トリガーを推論します。
  • 詳細な調査には、完全な event コンテキストを使用します。

これらのプラクティスは、開発パイプラインとデプロイ パイプライン全体でワークフローの信頼性をデバッグ、監査、および向上するのに役立ちます。

構成ファイルを読み取ってワークフロー効果を理解する

構成ファイルの読み取りによるワークフローの影響を理解するには、.ymlに格納されている.github/workflows/ ファイルの構造と内容を分析します。

ワークフロー構成ファイルは、ワークフローに関する次の情報を指定します。

  • 実行時 (on セクション)。
  • それが何をするか( jobs と stepsで)。
  • 実行場所 ( runs-on セクション)。
  • なぜ実行するのか（テスト、デプロイ、リンティングなどの目的）
  • 特定の条件 (環境、フィルター、ロジック) での動作。

ワークフロー効果を解釈する

  1. トリガーを特定します。

    ワークフローを開始したアクションを特定するには、ワークフローの on セクションを参照してください。

    例えば次が挙げられます。

    on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:

    このワークフローの例:

    • コードがメイン ブランチ (push) にプッシュされると、自動的に実行されます。
    • pull request が作成または更新されたときに実行されます (pull_request)。
    • ユーザー (workflow_dispatch) によって手動でトリガーできます。

  2. ワークフロー ジョブとステップを特定します。

    ワークフローの動作を確認するには、ワークフローの jobs と steps のセクションを参照してください。

    例えば次が挙げられます。

    jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

    このワークフローの例:

    • Linux 仮想環境 (runs-on) を使用します。
    • リポジトリのコード (steps>name) をチェックアウトします。
    • プロジェクトの依存関係 (steps>name) をインストールします。
    • 自動テスト (steps>name) を実行します。

  3. ワークフローの目的と結果を評価します。

    構成ファイルを読み取ることで、ワークフローの意図した結果を記述できます。

    "このワークフローは継続的インテグレーション (CI) パイプラインです。 これにより、リポジトリにプッシュされた、または pull request を介して送信された新しいコードが自動的にテストされます。 テストが失敗した場合、GitHub ワークフロー UI にこの結果が表示され、コードの品質を維持するのに役立ちます。"

  4. ワークフローの実行方法に影響を与えるオプションの機能を特定または設定します。

    • env は環境変数を設定します。
    • if では、条件が満たされた場合にのみ特定のステップを実行する条件付きロジックが追加されます。
    • timeout-minutes または continue-on-error ワークフローの実行とエラー処理を設定します。

失敗したワークフロー実行を診断する

  1. リポジトリで、[ アクション] タブに移動します。

  2. 失敗した実行を見つけます (通常は赤い X で示されます)。

  3. 失敗したワークフローを選択して、実行の概要を開きます。

  4. ワークフロー ログで、エラーを確認します。

    1. 実行の概要で、失敗を示すジョブが見つかるまで各ジョブとステップを展開します。

    2. ジョブまたはステップを選択してログを表示します。

    3. 検索対象:

      • エラー メッセージ
      • スタック トレース
      • 終了コード

    たとえば、失敗したテストには、 npm ERR! Test failed または exit code 1が表示される場合があります。

  5. ワークフロー構成ファイルを確認します。

    .yml ファイルを使用して、以下を確認します。

    • 各ステップで何をしようとしたのですか?
    • 実行に影響する環境変数 (env) または条件 (if) がある場合。
    • エラーが依存関係の不足、構文エラー、または手順の誤った設定によって発生した場合。

    ステップが失敗した場合は、次の原因を確認します。

    • 前の手順で依存関係が正常にインストールされましたか?
    • テスト ファイルは存在し、ローカルに渡されますか?

一般的な失敗シナリオ

次の表では、一般的なワークフローエラーのシナリオについて説明します。

症状 考えられる原因
ステップが失敗し、 command not foundl が返されます 依存関係がないか、セットアップが間違っている
npm install 失敗。 破損した package-lock.json ファイルまたはネットワークの問題
テスト ステップの失敗 単体テストの問題、構成ファイルが見つからない、または無効なテスト構文
Permission denied が表示されます。 ファイルのアクセス許可が正しくないか、シークレットが見つからない

GitHub でワークフロー ログにアクセスする方法を特定する

  1. リポジトリで、[ アクション] タブに移動します。

  2. ワークフローの一覧で、関連するワークフローを選択します。

    たとえば、 .yml ファイルに次のコードがある場合、 CI Workflow という名前のリンクが一覧に表示されます。

    name: CI Workflow

  3. 特定の実行を選択します。

    状態を示す実行の一覧で、検査する特定の実行のタイムスタンプまたはコミット メッセージを選択します。

  4. 各ジョブとステップを展開します。

    実行の概要ページには、ワークフロー ファイルで定義されているジョブ (ビルドやテストなど) が表示されます。

    1. ジョブを選択して展開します。
    2. ジョブ内で、"依存関係のインストール" や "テストの実行" など、個々の手順を展開します。

  5. ログ出力を表示します。

    コンソール ログ、エラー メッセージ、デバッグ情報など、ログ出力全体を表示するには、ワークフロー ステップを選択します。 ログをコピー、検索、ダウンロードできます。

次の表は、ワークフロー ログにアクセスするために実行する手順をまとめたものです。

アクション 目的
[アクション] タブ すべてのワークフロー実行を表示します。
ワークフロー名を選択する ワークフロー別に実行をフィルター処理します。
実行を選択する 特定のジョブとステップの結果を確認します。
ステップを展開する 詳細なログを表示します。
ログのダウンロード オフラインまたはチームのトラブルシューティング用のログをダウンロードします。

ビルドのアクション ログ

ワークフローを実行すると、発生した内容やエラーやテストエラーの詳細を含むログが生成されます。

エラーが発生した場合、またはテストが失敗した場合は、ログに緑色のチェックマークではなく赤い X が表示されます。 エラーまたは障害の詳細を調べて、何が起こったのかを調査できます。

失敗したテストの詳細を含む GitHub Actions ログのスクリーンショット。

成果物を操作する

ワークフローがログ エントリ以外のものを生成すると、成果物は 成果物と呼ばれます。 たとえば、Node.js ビルドでは、デプロイできる Docker コンテナーが生成されます。 コンテナーは、 アクション/upload-artifact アクション を使用してストレージにアップロードできる成果物です。 後で アクション/download-artifact を使用して、ストレージから成果物をダウンロードできます。

成果物を保存すると、それはジョブ間で保持されます。 各ジョブでは VM の新しいインスタンスが使用されるため、VM に保存して成果物を再利用することはできません。 別のジョブで成果物が必要な場合は、1 つのジョブ内のストレージに成果物をアップロードし、もう一方のジョブ用にダウンロードできます。

アーティファクト ストレージ

アーティファクトは GitHub のストレージ領域に格納されます。 この領域はパブリック リポジトリでは無料で、一部のストレージはアカウントに応じてプライベート リポジトリ用に無料です。 GitHub では、アーティファクトが 90 日間保存されます。

次のワークフロー スニペットでは、 actions/upload-artifact@main アクションに path 属性があることに注意してください。 この属性の値は、成果物を格納するパスです。 この例では、すべてをディレクトリにアップロードする public/ を指定します。 1 つのファイルのみをアップロードする場合は、 public/mytext.txtのようなものを使用します。

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

テスト用に成果物をダウンロードするには、ビルドが正常に完了し、成果物をアップロードする必要があります。 次のコードでは、テスト ジョブがビルド ジョブに依存することを指定します。

test:
    needs: build
    runs-on: ubuntu-latest

次のワークフロー スニペットでは、成果物をダウンロードします。 今では、テストジョブがテストのために成果物を使用できるようになりました。

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

ワークフローで成果物を使用する方法の詳細については、「ワークフロー データを成果物として格納する」を参照してください。

ワークフローを使用して GitHub でレビューを自動化する

pushやpull-requestなどの GitHub イベントを使用してワークフローを開始するだけでなく、スケジュールに従って、または GitHub 外のイベントの後にワークフローを実行することもできます。

レビュー担当者がプル要求を承認した後など、ユーザーが特定のアクションを完了した後にのみワークフローを実行できます。 このシナリオでは、 pull-request-reviewでトリガーできます。

実行できるもう 1 つのアクションは、pull request にラベルを追加することです。 この場合は、pullreminders/label-when-approved-action アクションを使います。

例えば次が挙げられます。

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

env ブロックでは、アクションの環境変数を設定します。 たとえば、ワークフローの実行に必要な承認者の数を設定できます。 この例では、1 つです。 アクションはラベルを追加してリポジトリに変更を加える必要があるため、 secrets.GITHUB_TOKEN 認証変数が必要です。 最後に、追加するラベルの名前を入力します。

ラベルの追加は、マージなどの別のワークフローを開始するイベントである可能性があります。 このイベントについては、次のモジュールで取り上げます。GitHub Actions での継続的デリバリーの使用について説明します。