Tips - ワークフローの監視

Posted at 2025-12-23

Tips - ワークフローの監視

GitHub Actionsのワークフロー監視機能は、CI/CDパイプラインの可視性を大幅に向上させます。本記事では、公式ドキュメントに基づいて、実践的な監視とトラブルシューティングの手法を体系的に解説します。

1. ワークフローステータスの可視化

1.1 ステータスバッジの実装

ワークフローの現在の状態を一目で確認できるステータスバッジは、README.mdに配置することで、プロジェクトの健全性を素早く伝えることができます。

1.1.1 基本的な実装方法

UIからの設定:

リポジトリのActionsタブに移動
対象のワークフローを選択
「Filter workflow runs」フィールドの横にある3点メニューをクリック
「Create status badge」を選択
MarkdownをコピーしてREADME.mdに貼り付け

ワークフローファイル名を使用する方法:

![ワークフロー状態](https://github.com/組織名/リポジトリ名/actions/workflows/main.yml/badge.svg)

1.1.2 フィルタリングオプション

特定ブランチの状態を表示:

![feature-1ブランチ](https://github.com/組織名/リポジトリ名/actions/workflows/main.yml/badge.svg?branch=feature-1)

特定イベントによる実行状態を表示:

![pushイベント](https://github.com/組織名/リポジトリ名/actions/workflows/main.yml/badge.svg?event=push)

これにより、プルリクエストやpushイベントなど、トリガーイベント別の状態を追跡できます。

1.2 ビジュアライゼーショングラフ

ワークフロー実行時にリアルタイムで生成されるグラフは、ジョブ間の依存関係と実行状態を視覚的に把握できます。

グラフ上の各ジョブをクリックすることで、そのジョブのログに直接アクセスできます。依存関係は線で表現され、並列実行と順次実行の違いが明確になります。

1.2.1 自動追加されるステップ

GitHubは、ワークフローファイルに設定されたステップに加えて、各ジョブの実行を準備・完了するために2つの追加ステップを自動的に生成します:

Set up job: ランナーの初期化とセットアップ処理を実行
Complete job: ジョブ実行の後処理とクリーンアップを実行

これらのステップはワークフロー実行ログに記録され、実行時間も計測されます。

GitHub-hostedランナーの場合、「Set up job」にはランナーイメージの詳細と、ランナーマシンにプリインストールされているツールのリストへのリンクが含まれます。これにより、利用可能なツールのバージョンや環境を確認できます。

1.3 ワークフロー実行履歴の表示

各ワークフローの実行履歴を時系列で確認できます。これにより、過去の実行状態やパターンを分析できます。

表示手順:

リポジトリのActionsタブに移動
左サイドバーから対象のワークフローを選択
ワークフロー実行のリストから、確認したい実行の名前をクリック
ワークフロー実行サマリーが表示される

実行履歴には、各実行の状態（成功、失敗、キャンセル、中立）、実行時間、トリガーイベント、実行者などの情報が含まれます。

1.4 ジョブ実行時間の表示

各ジョブの実行時間を確認することで、パフォーマンスのボトルネックを特定できます。

表示手順:

リポジトリのActionsタブに移動
左サイドバーから対象のワークフローを選択
ワークフロー実行のリストから、確認したい実行の名前をクリック
ジョブサマリーの下に、各ジョブの実行時間が表示される

1.4.1 課金対象時間の確認

プライベートリポジトリでGitHub-hostedランナーを使用する場合、課金対象となる実行時間を確認できます。

確認手順:

ワークフロー実行サマリーページを表示
左サイドバーの「Run details」の下にある「Usage」をクリック
課金対象のジョブ実行時間の詳細が表示される

重要な注意点:

課金対象分数は、プライベートリポジトリでGitHub-hostedランナーを使用するジョブにのみ表示されます
パブリックリポジトリでGitHub Actionsを使用する場合、課金対象分数は発生しません
セルフホストランナーで実行されるジョブにも課金対象分数は発生しません
表示される課金時間には分数の倍率は含まれていません。合計使用量（倍率を含む）を確認するには、GitHubの使用量ページを参照してください
課金対象時間は次の分単位に切り上げられます

2. ログ管理とトラブルシューティング

2.1 ログの表示と検索

2.1.1 失敗の診断手順

リポジトリのActionsタブに移動
左サイドバーから対象のワークフローを選択
ワークフロー実行のリストから、失敗した実行をクリック
Jobsセクションまたはビジュアライゼーショングラフから失敗したジョブを選択
失敗したステップは自動的に展開されて表示される

2.1.2 ログ内検索

ログが展開された状態で、右上の検索ボックスを使用して特定のキーワードを検索できます。これは大量のログから問題箇所を特定する際に非常に有効です。

# 例: エラーメッセージの検索
# 検索キーワード: "error", "failed", "ENOENT"

2.1.3 特定行へのリンク

ログの行番号をクリックすると、その行へのパーマリンクが取得できます。これをチームメンバーと共有することで、問題箇所を正確に伝えることができます。

2.2 ログのダウンロード

ログアーカイブをダウンロードすることで、オフラインでの分析や長期保存が可能になります。

手順:

ワークフロー実行のサマリーページに移動
右上の歯車アイコンをクリック
「Download log archive」を選択

注意点: 部分的に再実行されたワークフローのログアーカイブには、再実行されたジョブのみが含まれます。完全なログセットが必要な場合は、以前の実行のアーカイブも取得してください。

2.3 ログの削除

2.3.1 Web UIからの削除

ワークフロー実行のサマリーページに移動
右上の3点メニューをクリック
「Delete all logs」を選択
確認プロンプトを承認

2.3.2 スクリプトによる一括削除

複数のワークフロー実行のログを効率的に削除するために、以下のスクリプトを使用できます。

#!/usr/bin/env bash

# 特定ワークフローの全ログを削除
# 使用方法: delete-logs.sh <リポジトリ> <ワークフローファイル名>

set -oe pipefail

REPOSITORY=$1
WORKFLOW_NAME=$2

# 引数の検証
if [[ -z "$REPOSITORY" ]]; then
  echo "リポジトリ名が必要です"
  exit 1
fi

if [[ -z "$WORKFLOW_NAME" ]]; then
  echo "ワークフロー名が必要です"
  exit 1
fi

echo "$REPOSITORY の $WORKFLOW_NAME ワークフローの完了した実行を取得中"

RUNS=$(
  gh api \
    -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2022-11-28" \
    "/repos/$REPOSITORY/actions/workflows/$WORKFLOW_NAME/runs" \
    --paginate \
    --jq '.workflow_runs[] | select(.conclusion != "") | .id'
)

echo "$WORKFLOW_NAME ワークフローの完了した実行を $(echo "$RUNS" | wc -l) 件発見"

# 各実行のログを削除
for RUN in $RUNS; do
  echo "実行 $RUN のログを削除中"
  gh api \
    --silent \
    --method DELETE \
    -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2022-11-28" \
    "/repos/$REPOSITORY/actions/runs/$RUN/logs" || echo "実行 $RUN のログ削除に失敗"

  # レート制限を回避するため100ms待機
  sleep 0.1
done

スクリプトの実行:

chmod +x delete-logs.sh
./delete-logs.sh yamada-taro/my-project ci.yaml

2.4 GitHub CLIを使用したログ表示

# 特定の実行のログを表示
gh run view RUN_ID --log

# 特定のジョブのログを表示
gh run view --job JOB_ID --log

# ログ内を検索
gh run view --job JOB_ID --log | grep error

# 失敗したステップのみを表示
gh run view --job JOB_ID --log-failed

3. メトリクスによるパフォーマンス分析

3.1 組織レベルのメトリクス表示

アクセス方法:

右上のプロフィール画像をクリック
「Organizations」を選択
対象の組織をクリック
「Insights」タブに移動
「Actions Usage Metrics」または「Actions Performance Metrics」を選択

3.2 リポジトリレベルのメトリクス表示

アクセス方法:

リポジトリのメインページに移動
「Insights」タブをクリック
「Actions Usage Metrics」または「Actions Performance Metrics」を選択

3.3 期間選択オプション

メトリクスの表示期間を以下から選択できます:

期間	説明
今週 (月-日)	月曜日から現在の日までのデータ
今月	月初から現在の日までのデータ
先月	前月の初日から最終日までのデータ
過去30日	過去30日間のデータ
過去90日	過去90日間のデータ
昨年	過去12ヶ月の集計データ
カスタム	最大100日間の任意の期間（最大1年前まで）

3.4 フィルタリング機能

メトリクスをフィルタリングして、特定の条件に合致するデータのみを表示できます:

フィルタの作成手順:

「Filter」ボタンをクリック
「Add a filter」を選択
フィルタリングしたいメトリクスを選択
「Qualifier」「Operator」「Value」列に情報を入力
必要に応じて追加のフィルタを作成
「Apply」をクリック

3.5 データのエクスポート

右上のエクスポートボタンをクリックすることで、メトリクスデータをCSV形式でダウンロードできます。これにより、スプレッドシートでの詳細な分析や、カスタムダッシュボードの作成が可能になります。

3.6 注意点

Workflowsタブのジョブ数とJobsタブのジョブ数には、一意なジョブの識別方法の違いにより差異が生じる場合がありますが、これは計算される合計時間には影響しません。

デバッグログの活用

標準のワークフローログでは問題の原因を特定できない場合、追加のデバッグログを有効にすることができます。

ランナー診断ログの有効化

ランナー診断ログは、ジョブを実行するランナーの動作に関する詳細情報を提供します。

有効化方法:

リポジトリに以下のシークレットまたは変数を設定:

名前: ACTIONS_RUNNER_DEBUG
値: true

生成されるログファイル:

ランナープロセスログ: ランナーの調整とセットアップ情報
ワーカープロセスログ: ジョブの実行情報

これらのログは、ダウンロードしたログアーカイブ内のrunner-diagnostic-logsフォルダに格納されます。

4.2 ステップデバッグログの有効化

ステップデバッグログは、各ステップの詳細な実行情報を出力します。

有効化方法:

リポジトリに以下のシークレットまたは変数を設定:

名前: ACTIONS_STEP_DEBUG
値: true

動作:

設定後、ステップログに追加のデバッグイベントが表示され、各ステップの詳細な動作を確認できます。

4.3 シークレットと変数の優先順位

シークレットと変数の両方が設定されている場合、シークレットの値が優先されます。セキュリティ上の理由から、機密性の高い設定にはシークレットの使用を推奨します。

5. トラブルシューティングの実践

5.1 初期診断のアプローチ

5.1.1 GitHub Copilotによるエラー解析

失敗したワークフロー実行に対して、GitHub Copilotを使用した迅速な診断が可能です:

方法1: マージボックス内の失敗したチェックの横にある3点メニューから「Explain error」を選択

方法2: ワークフロー実行サマリーページの上部にある「Explain error」をクリック

Copilotがエラーの原因と解決方法を提案します。ただし、GitHub Copilot Freeサブスクリプションの場合、月間のチャットメッセージ制限にカウントされます。

5.2 ワークフロートリガーの診断

5.2.1 一般的なトリガー問題

イベント制限:

issues、scheduleなどのイベントはデフォルトブランチからのみ実行されます
デフォルトブランチ以外のワークフローファイルでは、これらのイベントはトリガーされません

マージコンフリクト:

プルリクエストにマージコンフリクトがある場合、pull_requestイベントではワークフローが実行されません

スキップアノテーション:

コミットメッセージにスキップ指示が含まれている場合、pushまたはpull_requestイベントでのワークフロー実行がスキップされます

スケジュール実行の遅延:

GitHub Actionsの負荷が高い時間帯（特に毎時0分）には、スケジュール実行が遅延する可能性があります
負荷分散のため、時刻の開始時を避けてスケジュールを設定することを推奨します

5.2.2 フィルタリングの制限

パスフィルタリング:

on:
  push:
    paths:
      - 'src/**'
      - '!src/docs/**'

パスフィルタリングの評価は最初の300ファイルに制限されます。変更されたファイルが300ファイルを超え、フィルタに一致するファイルが最初の300ファイル内に含まれていない場合、ワークフローは実行されません。

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

5.3.1 ワークフローのキャンセル

通常のキャンセル操作が期待通りに動作しない場合、条件文の設定が原因の可能性があります。

問題のある設定例:

jobs:
  build:
    runs-on: ubuntu-latest
    if: always()  # キャンセル時でも実行を継続
    steps:
      - name: ビルド
        run: npm run build

推奨される設定:

jobs:
  build:
    runs-on: ubuntu-latest
    if: ${{ !cancelled() }}  # キャンセル時は実行しない
    steps:
      - name: ビルド
        run: npm run build

UIやAPIでキャンセルが処理されない場合、REST APIを使用して強制キャンセルできます。

5.4 ランナーのトラブルシューティング

5.4.1 ラベルの定義

GitHub-hostedランナーは、actions/runner-imagesリポジトリで管理されている事前設定されたラベルを使用します。

ラベル競合の回避:

ラージランナーやセルフホストランナーには、既存のプリセットラベルと重複しない一意のラベル名を使用してください。ラベルが一致する場合、どのランナーでジョブが実行されるか保証されません。

# 推奨されないラベル使用例
runs-on: ubuntu-latest  # GitHubホストランナーと競合する可能性

# 推奨されるラベル使用例
runs-on: [self-hosted, linux, x64, my-company-prod]

5.4.2 セルフホストランナー

セルフホストランナーを使用している場合、アクティビティの表示と一般的な問題の診断が可能です。セルフホストランナーの監視とトラブルシューティングに関する詳細なドキュメントを参照してください。

5.5 予算設定による課金エラーの解決

ワークフローが課金や容量の上限エラーで失敗する場合、Actionsの予算を設定することで即座に問題を解消できる可能性があります。予算を設定することで、設定した予算額まで追加の分数と容量の使用が課金されます。

5.5 予算設定による課金エラーの解決

5.6 ネットワーク関連の診断

5.6.1 GitHub Status の確認

ネットワーク問題の診断を開始する前に、GitHub Statusでプラットフォームの現在のステータスを確認してください。

5.6.2 DNS問題

DNS設定、解決、リゾルバーに関する問題が発生する場合があります:

利用可能なログを確認
ベンダーのドキュメントを参照
ネットワーク管理者に相談

5.6.3 ファイアウォール

ファイアウォールによってアクティビティがブロックされる可能性があります:

対応:

ファイアウォールログを確認
ベンダーのドキュメントを参照
ネットワーク管理者に相談

5.6.4 プロキシ設定

プロキシを使用した通信で失敗が発生する場合:

ランナーアプリケーションのプロキシ設定を確認
公式ドキュメント「ランナーでのプロキシサーバーの使用」を参照
ベンダーのドキュメントを確認
ネットワーク管理者に相談

5.6.5 IPアドレスリスト

IP許可リストまたは拒否リストが通信を妨げる可能性があります。

GitHub-hostedランナーのIPアドレス:

GitHubのIPアドレスに関する情報は、公式ドキュメント「GitHubのIPアドレスについて」を参照してください。

静的IPアドレス:

ラージランナーでは静的IPアドレスの使用が可能です。詳細は「ラージランナーの管理」を参照してください。

5.6.6 証明書

自己署名証明書やカスタム証明書チェーンに関する問題:

証明書の有効期限を確認
証明書が信頼されているか確認
curlなどのツールで証明書を検査
ベンダーのドキュメントを参照
ネットワーク管理者に相談

5.6.7 Azure プライベートネットワーク

Azure Virtual Networks (VNETs) 内でGitHub-hostedランナーを使用している場合に問題が発生する可能性があります。

詳細なトラブルシューティングについては、GitHub Enterprise Cloudドキュメントの組織向けおよびエンタープライズ向けのAzureプライベートネットワーク設定のトラブルシューティングに関するセクションを参照してください。

GitHub Supportの活用

提供すべき診断情報

GitHub Supportに問い合わせる際、以下の情報を提供することで解決を加速できます:

基本情報

ワークフロー実行のURL

例: https://github.com/組織名/リポジトリ名/actions/runs/0123456789

ワークフローYAMLファイル
- .txt形式で添付
- 複数のワークフローファイルが関係する場合はすべて提供
ワークフロー実行ログ
- 失敗例のログアーカイブ
- 特定の失敗パターンを示すログ

6.1.2 セルフホストランナーの場合

ランナーログ
- _diagフォルダ内のログファイル
- ファイル名形式: Runner_YYYY####-xxxxxx-utc.logおよびWorker_YYYY####-xxxxxx-utc.log

6.1.3 エフェメラルランナーの場合

GitHub Supportはエフェメラルランナーのアプリケーションログファイルをリクエストする場合があります。エフェメラルランナーからのログを転送・保存するメカニズムの実装が推奨されます。

6.1.4 Actions Runner Controllerの場合

コントローラー、リスナー、ランナーポッドの完全なログ
詳細はActions Runner Controllerエラーのトラブルシューティングに関するドキュメントを参照

6.1.5 CodeQL分析ワークフローの場合

CodeQLデバッグアーティファクト
- サンプルワークフロー実行からダウンロード
- .zip形式で提供
- ファイルサイズが大きい場合はサポートに相談

6.2 ファイルの添付方法

ファイルの拡張子を.txtまたは.zipに変更して添付
インラインでテキストデータを提供する場合は、Markdownコードブロックで適切にフォーマット
機密情報（トークン、シークレット）は適切に編集

6.3 サポート範囲外の項目

以下の項目はGitHub Supportの範囲外です:

サードパーティ統合（Jira、Jenkinsなど）
Azure DevOps（Azure Supportに連絡）
スクリプトの記述
外部認証システムの設定（SAML IDプロバイダーなど）
オープンソースプロジェクト
CodeQLの新しいクエリの記述やデバッグ
クラウドプロバイダーの設定（仮想ネットワーク、ファイアウォールなど）
コンテナオーケストレーション（Kubernetes設定やネットワーキング）
ワークフローとデータ管理の詳細な支援
GitHub Actionsカスタムイメージのカスタマイズとツールインストールの包括的サポート
プレビュー機能
GitHub Copilotの提案

これらのトピックについては、GitHub Expert Servicesが専門的なサービスを提供しています。

7. まとめ

GitHub Actionsのワークフロー監視は、以下の要素を組み合わせることで最大の効果を発揮します:

可視性の向上: ステータスバッジとビジュアライゼーショングラフによる状態の即座の把握
詳細な分析: ログの検索・ダウンロード機能による問題の深堀り
データドリブンな改善: メトリクスによるパフォーマンスの定量的評価
効率的なデバッグ: 適切なデバッグログの活用による迅速な問題解決
体系的なトラブルシューティング: 問題の種類に応じた診断アプローチ

これらの機能を活用することで、CI/CDパイプラインの信頼性と効率性を大幅に向上させることができます。問題が発生した際には、まずログとメトリクスを確認し、必要に応じてデバッグログを有効化し、それでも解決しない場合は適切な情報を準備してGitHub Supportに相談するという流れを確立しましょう。

継続的なモニタリングと改善のサイクルを回すことで、より堅牢で保守性の高いワークフローを構築できます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

Tips - ワークフローの監視

Tips - ワークフローの監視

目次

1. ワークフローステータスの可視化

1.1 ステータスバッジの実装

1.1.1 基本的な実装方法

1.1.2 フィルタリングオプション

1.2 ビジュアライゼーショングラフ

1.2.1 自動追加されるステップ

1.3 ワークフロー実行履歴の表示

1.4 ジョブ実行時間の表示

1.4.1 課金対象時間の確認

2. ログ管理とトラブルシューティング

2.1 ログの表示と検索

2.1.1 失敗の診断手順

2.1.2 ログ内検索

2.1.3 特定行へのリンク

2.2 ログのダウンロード

2.3 ログの削除

2.3.1 Web UIからの削除

2.3.2 スクリプトによる一括削除

2.4 GitHub CLIを使用したログ表示

3. メトリクスによるパフォーマンス分析

3.1 組織レベルのメトリクス表示

3.2 リポジトリレベルのメトリクス表示

3.3 期間選択オプション

3.4 フィルタリング機能

3.5 データのエクスポート

3.6 注意点

デバッグログの活用

ランナー診断ログの有効化

4.2 ステップデバッグログの有効化

4.3 シークレットと変数の優先順位

5. トラブルシューティングの実践

5.1 初期診断のアプローチ

5.1.1 GitHub Copilotによるエラー解析

5.2 ワークフロートリガーの診断

5.2.1 一般的なトリガー問題

5.2.2 フィルタリングの制限

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

5.3.1 ワークフローのキャンセル

5.4 ランナーのトラブルシューティング

5.4.1 ラベルの定義

5.4.2 セルフホストランナー

5.5 予算設定による課金エラーの解決

5.5 予算設定による課金エラーの解決

5.6 ネットワーク関連の診断

5.6.1 GitHub Status の確認

5.6.2 DNS問題

5.6.3 ファイアウォール

5.6.4 プロキシ設定

5.6.5 IPアドレスリスト

5.6.6 証明書

5.6.7 Azure プライベートネットワーク

GitHub Supportの活用

提供すべき診断情報

基本情報

6.1.2 セルフホストランナーの場合

6.1.3 エフェメラルランナーの場合

6.1.4 Actions Runner Controllerの場合

6.1.5 CodeQL分析ワークフローの場合

6.2 ファイルの添付方法

6.3 サポート範囲外の項目

7. まとめ