GitHub Actions の失敗ログ、まだ手動で読んでいませんか？ ども！龍ちゃんです。 CI が落ちたときの対応、毎回こうなっていませんか？ GitHub Actions の UI を開く 失敗した Run を探す 失敗したジョブを開く ログをスクロールしてエラー行を目視で探す エラーメッセージをコピーしてググる 地味に面倒なんですよね、これ。特にジョブが複数あるワークフローだと、どのジョブのどのステップで落ちたのかを探すだけで時間を食う。 これ、Agent Skills に任せたら1行で終わります。 Before After 操作 GitHub UI → ログ目視 → 手動分析 「CI失敗してるから原因を調べて」 所要時間 5〜10分 30秒 得られるもの エラー行のコピペ 原因分析 + 修正方針のレポート 本記事では、gh CLI を使った CI ログ自動分析スキルを GitHub Copilot の Agent Skills として実装する手順を解説します。Claude Code で同じスキルを作った「 gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決 」の Copilot 移植版です。 190行あった Claude Code 版の SKILL.md を、Copilot の 500 トークン制限に合わせて 58 行に圧縮する設計がメインの話題になります。 対象読者 Agent Skills で実用的なスキルを作りたい人 Claude Code のスキルを Copilot に移植したい人 CI/CD のデバッグを自動化したい人 Agent Skills の基本（ディレクトリ構造、SKILL.md の書き方）は「 【2026年版】Agent Skills 入門 」を参照してください。 GitHub Actions の失敗を Agent Skills で自動分析する 作り方の前に、まず完成形を見てください。こういうやりとりになります。 龍ちゃん CI失敗してるから原因を調べて GitHub Copilot 失敗した Run を特定します。 → gh run list –status failure –limit 5 → gh run view 22573804432 –json jobs → gh run view 22573804432 –log –job 65388009712 ## Failure Analysis Root Cause: integration test が HTTP 503 で失敗 Suggested Fix: サービスのヘルスチェックをテスト前に実行 1行のプロンプトで、失敗 Run の特定からログ取得、原因分析まで全自動。この動きを実現するスキルの作り方を、このあと順を追って解説します。 前提条件 VS Code + GitHub Copilot（Agent Mode が使える状態） gh CLI がインストール・認証済み（ gh auth status で確認） .github/skills/gh-workflow/ にスキルが配置済み（本記事で作ります） テスト用の失敗ワークフロー（demo-failure.yml） 検証用に、意図的に失敗するワークフローを用意しました。 name: Demo - Failure Workflow on: workflow_dispatch: jobs: setup: name: Setup runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Verify environment run: | echo "Environment check..." echo "OS: $(uname -s)" echo "Setup completed." test: name: Test runs-on: ubuntu-latest needs: setup steps: - name: Checkout repository uses: actions/checkout@v4 - name: Run unit tests run: | echo "Running unit tests..." echo "test_fetch_article ... PASSED" echo "test_parse_html ... PASSED" echo "Unit tests passed." - name: Run integration tests run: | echo "Running integration tests..." echo "" echo "FAILED: test_pipeline.py::test_full_pipeline" echo " AssertionError: Expected status code 200, got 503" echo " File: tests/test_pipeline.py, line 42" echo " assert response.status_code == 200" echo "" echo "1 passed, 1 failed in 3.42s" exit 1 deploy: name: Deploy runs-on: ubuntu-latest needs: test steps: - name: Deploy application run: echo "Deploying..." Setup → Test → Deploy の3ジョブ構成で、Test ジョブの integration tests が 503 エラーで exit 1 します。CI/CD でよくあるパターンを再現しています。 手動実行して失敗させておきます。 gh workflow run "Demo - Failure Workflow" # 30秒ほど待ってから確認 gh run list --workflow "demo-failure.yml" --limit 1 デモ 1：gh run list でクイックステータス確認 VS Code の Agent Mode で「CI確認して」と入力します。 スキルが発火すると、Copilot は SKILL.md の Mode 1（クイックステータス）に従い、 gh run list で最新の実行状況を一覧取得します。 実行されたコマンド： git branch --show-current gh run list --branch main --limit 10 --json databaseId,status,conclusion,name,headBranch,event,createdAt,displayTitle 出力（Copilot のレポート）： 日時 ワークフロー名 ステータス Run ID 3/2 11:23 Demo – Failure Workflow failure 22573804432 2/26 06:20 Demo – Failure Workflow failure 22430458939 2/26 06:20 Demo – CI Pipeline success 22430440934 2/26 06:19 Demo – CI Pipeline success 22430416062 「最新の CI が失敗しています」と報告したうえで、「失敗ログを分析しますか？」と次のアクションを提案してくれます。ブランチ取得から一覧表示まで自動で、自分が打つのはプロンプト1行だけです。 デモ 2：gh run view –log で失敗ログを自動分析 ここがメインのデモです。「3/2に失敗したものを取得してほしい」と入力すると、スキルの Mode 4（ログ分析）が起動します。 Copilot は SKILL.md に書かれた Progressive Filtering （段階的絞り込み）の手順に従って、4ステップで自動分析します。 Step 1: 失敗 Run の特定 gh run view 22573804432 --json jobs,status,conclusion,createdAt,updatedAt,headBranch,event,workflowName Run 全体の情報を取得。3ジョブの中から Test ジョブが failure であることを特定。 Step 2: 失敗ジョブの絞り込み JSON レスポンスから失敗ジョブの ID（65388009712）を抽出。Step 4 の「Run integration tests」が failure であることを確認。 Step 3: ログ取得 gh run view 22573804432 --log --job 65388009712 --log は必ず --job と併用します。これは SKILL.md の Token Efficiency Rules で定義したルールです。 --job なしだと全ジョブのログが出力されてトークンを大量消費するので、失敗ジョブに絞って取得します。 Step 4: エラー分析とレポート出力 ## Failure Analysis **Run:** #22573804432 - Demo - Failure Workflow **Branch:** main | Job | Error Summary | |-----|--------------| | Test | AssertionError: Expected status code 200, got 503 | **Root Cause:** Integration test `test_pipeline.py::test_full_pipeline` が失敗。 外部サービスへの接続で HTTP 503 (Service Unavailable) を受信。 **Suggested Fix:** 1. サービスのヘルスチェックをテスト前に実行 2. テストエンドポイントへのネットワーク接続を確認 3. テストデータ・環境設定を見直し Run 全体 → 失敗ジョブ → 失敗ステップ → エラー行と、段階的に絞り込んで 503 エラーを特定し、原因と修正方針をレポートにまとめてくれました。これが Progressive Filtering の実際の動きです。 デモ 3：英語プロンプトでの発火確認 description に英語キーワードも埋め込んであるので、英語でも発火します。 「Analyze the GitHub Actions error logs」と入力すると、同じく Progressive Filtering が走り、英語で Failure Analysis Report が出力されました。日本語チームと英語チームが混在する環境でも使えます。 Copilot 用 SKILL.md の作り方：190行→58行に圧縮する設計 やっと本題です。ここが一番悩んだところで、Claude Code 版の SKILL.md（190行）を Copilot の制約に合わせて58行に圧縮する設計を解説します。 ディレクトリ構成と配置ルール .github/ ├── copilot-instructions.md ← ルーティング追記 ├── skills/ │ └── gh-workflow/ │ ├── SKILL.md ← 本体（58行・219語） │ └── references/ │ └── commands.md ← 詳細情報（79行・266語） └── workflows/ ├── demo-failure.yml ← テスト用（意図的に失敗） └── demo-success.yml ポイント： ファイル名は SKILL.md （大文字必須） ディレクトリ名は kebab-case で name フィールドと一致させる Claude Code 版（ .claude/skills/gh-workflow/ ）とは別ディレクトリなので、両方共存できる SKILL.md と references/ の分離基準 GitHub Copilot には SKILL.md に対する 500 トークン制限 （約60行・300語以内）があります。Claude Code にはこの制限がないので、190行の SKILL.md がそのまま動いていましたが、Copilot ではそうはいきません。 圧縮の方針は「SKILL.md はルーター、詳細は references/ に分離」です。 分類 SKILL.md に残す references/commands.md に分離 モード判定 4モードのテーブル（4行） – Token Efficiency Rules 必須ルール4項目 – 各モードの手順 概要（主なコマンド1行ずつ） JSON 出力パターン全文 レポートテンプレート – ステータス一覧 + 失敗分析テンプレート Status/Conclusion 一覧 – 12行の値テーブル Important Notes – 4項目の注意事項 残す基準 : Copilot がスキルを実行するときに「最初に読む必要がある情報」だけ残す。モード判定（何をすべきか）とトークン効率ルール（やってはいけないこと）。この2つがないと、Copilot は最初の一歩を踏み出せません。 分離する基準 : 必要になったタイミングで参照すればいい情報。JSON の出力パターンやレポートテンプレートは、実行が進んだ段階で references/ から読み込めば十分です。「あとで見ればいいもの」は全部 references/ に押し出す。割り切りが大事でした。 Copilot の Progressive Disclosure（関連度に基づいて必要なファイルだけ読み込む仕組み）がこの分離設計と噛み合います。SKILL.md を読んでモードを判定し、実行に必要な詳細情報を references/ から追加で読む、という流れになるわけです。 圧縮結果： Claude Code 版 Copilot 版 SKILL.md 190行 58行（219語） 参照ファイル なし（全部入り） references/commands.md（79行・266語） 合計 190行 137行（2ファイル） 行数の合計はあまり変わりませんが、SKILL.md 単体が 500 トークン予算の 73% に収まっているのがポイントです。 description の書き方：単一行で書く鉄則 description は Copilot がスキルを選ぶかどうかを判定する 最重要フィールド です。ここの設計が発火率を左右します。 鉄則：description は単一行で書く。 description: | の複数行記法は使わない。 # NG: 複数行記法 → Copilot が "|" だけ読み込んでしまう description: | GitHub Actions の Workflow 状態確認とログ分析を行うスキル。 Use when: CIが失敗した原因を調べたい。 # OK: 単一行 → Copilot が全文を正しく読み込む description: GitHub Actionsのワークフロー状態確認と失敗ログ分析を行うスキル。gh CLIでCI/CDのログ取得から原因分析まで実行する。Use when: CIが失敗した原因を調べたい、ワークフローの状態を確認したい、PRのチェック結果を見たい。Triggers on: CI確認, Workflow確認, CI失敗, ログ分析, GitHub Actions debug,CI status check, workflow failure, PRチェック, エラーログ, pipeline debug. GitHub Copilot のスキルローダーは YAML の複数行記法（ description: | ）を正しくパースできません。 | という文字列だけが description として読み込まれ、発火判定に使われる情報がほぼゼロになります。Claude Code ではこの問題は起きないので、移植時に見落としがちな落とし穴です。 description に含める3要素： 機能説明 — 何をするスキルか Use when — どういう場面で使うか（ユーザーの意図） Triggers on — 発火キーワード（日本語 + 英語） Copilot は description の文字列とユーザーの発話の 類似度 でスキルを選ぶので、「ユーザーが実際に言いそうな言葉」を入れておくのがコツです。 description の設計思想や、なぜ発火しないのかの原因分析は「 Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？原因と解決策 」で詳しく解説しています。本記事では実装だけ押さえて先に進みます。 copilot-instructions.md でスキル発火を安定させる description だけでは発火が不安定な場合の補強策として、 copilot-instructions.md にルーティングテーブルを追加します。copilot-instructions.md は Agent Mode で常に読み込まれるファイルなので、ここにスキルへの道しるべを書いておくと発火が安定します。 ## Agent Skills Routing | キーワード | スキル | パス | |-----------|--------|------| | CI確認, Workflow, GitHub Actions, ログ分析, CI失敗, pipeline debug | gh-workflow | `.github/skills/gh-workflow/SKILL.md` | 既存の copilot-instructions.md の末尾に追記するだけです。中身は触らない。 注意点として、ルーティングに登録するスキルは 重要なもの3〜5個に絞る べきです。copilot-instructions.md に書いた内容は毎回のコンテキストに含まれるので、スキル全部を登録するとトークンを無駄遣いします。 この手法の効果と限界は「 Agent Skillsが動かない？ 」の「解決策③：Instructions ルーティング」セクションで検証データ付きで解説しています。 allowed-tools の検証：agentskills.io 仕様と実装のギャップ SKILL.md のフロントマターには allowed-tools というフィールドがあります。スキルが使ってよいツールを制限する仕組みです。今回のスキルでは以下のように書きました。 allowed-tools: Bash(gh:*) Bash(git:*) Bash(jq:*) Read 「gh CLI と git と jq のコマンド実行、それとファイル読み取りだけ許可する」という意味です。 agentskills.io Specification での定義 agentskills.io の仕様 では、 allowed-tools は正式なオプションフィールドとして定義されています。ただし Experimental（実験的） ステータスで、”Support for this field may vary between agent implementations” と注記されています。 記法は2パターンあります： # パターン記法（コマンドプレフィックス指定） allowed-tools: Bash(gh:*) Bash(git:*) Read # ツール名列挙（MCP ツール等） allowed-tools: list_workflow_runs summarize_job_log_failures get_job_logs GitHub Copilot での動作検証結果 結論から言うと、 現時点では allowed-tools の enforcement（強制）は実装されていません 。 今回の検証では、 allowed-tools を書いた状態でスキルは正常に発火し、gh CLI のコマンドも問題なく実行されました。一方で、 allowed-tools に列挙していないツールの使用を制限する動作は確認できませんでした。 確認項目 結果 スキルの発火 問題なし（allowed-tools が発火を妨げない） allowed-tools 内のツール使用 問題なし allowed-tools 外のツール制限 未確認（制限が効いている証拠なし） VS Code バリデータの警告 Issue #14131 として報告済み（Open、対応予定なし） allowed-tools はスキル選択時には参照されず、スキル実行時に SKILL.md の本文を読んだ段階で「ガイドライン」として機能している可能性があります。強制力のあるサンドボックスではなく、エージェントへの「お願い」に近い位置づけです。 コミュニティの allowed-tools 実装例 参考までに、 heilcheng/awesome-agent-skills の github-actions-failure-debugging スキルを見ると、 allowed-tools はフロントマターに書かず、本文テキスト内で手順として使用ツールを記述しています。 To debug failing GitHub Actions workflows: 1. Use `list_workflow_runs` to look up recent workflow runs 2. Use `summarize_job_log_failures` to get an AI summary of failed jobs 3. Use `get_job_logs` for full detailed failure logs if needed フロントマターの allowed-tools で制限するか、本文で手順として指示するか。enforcement が実装されていない現時点では、本文に書くほうが確実にエージェントに伝わります。 正直どちらにするか迷ったんですが、自分のスキルでは「両方書いておく」方針にしました。フロントマターは将来の enforcement が来たときの保険、本文は今のエージェントへの確実な指示。二重管理にはなりますが、壊れるリスクよりマシだと判断しています。 Claude Code 版 SKILL.md との違い（比較表） 同じ gh-workflow スキルの Claude Code 版と Copilot 版を比較します。 変わる点：description・トークン予算・ファイル構成 比較項目 Claude Code 版 Copilot 版 ファイルパス .claude/skills/gh-workflow/ .github/skills/gh-workflow/ SKILL.md 行数 190行（1ファイル完結） 58行 + references/commands.md description トリガー文字列列挙 単一行で Use when + Triggers on allowed-tools Bash, Read Bash(gh:*) Bash(git:*) Bash(jq:*) Read 参照ファイル分離 不要（全文コンテキストに読み込み） 必須（500トークン制限） copilot-instructions.md 不要 ルーティング追記推奨 一番大きいのは「トークン予算」です。Claude Code は SKILL.md を丸ごと読み込めるので圧縮の必要がなく、190行でも問題ありません。Copilot は 500 トークン制限があるので、references/ への分離が必須になります。 変わらない点：gh CLI コマンド・Progressive Filtering 比較項目 Claude Code / Copilot 共通 gh CLI コマンド 同一（ gh run list , gh run view --log --job 等） Progressive Filtering 同一（一覧→ジョブ特定→ログ取得→分析の4ステップ） Token Efficiency Rules 同一（ --log は --job と併用、 watch 禁止等） Report Template 同一（references/commands.md に移植済み） gh CLI のノウハウはそのまま使えます。変えるのはスキルの外側（配置・description・トークン予算）だけで、中身は同じものが動きます。 リポジトリ/ ├── .claude/skills/gh-workflow/SKILL.md ← Claude Code版（190行・1ファイル完結） ├── .github/skills/gh-workflow/ ← Copilot版（58行 + references/） │ ├── SKILL.md │ └── references/commands.md └── （両方共存可能・互いに干渉しない） ちなみに GitHub Copilot は .claude/skills/ 配下のファイルも読み込みます。つまり Claude Code 用に作ったスキルが Copilot 側でも認識される。ただし 190 行の SKILL.md だとトークン予算を超えるし、 description: | の複数行記法は Copilot で壊れるので、そのまま期待どおりに動くかは別問題です。Claude Code ユーザーが Copilot でも使いたいなら、本記事のように .github/skills/ に圧縮版を別途置くのが確実です。 まとめ CI が落ちたら「CI失敗してるから原因を調べて」。それだけで原因分析から修正方針までレポートが出てきます。 やることは .github/skills/gh-workflow/ に SKILL.md と references/commands.md を置くだけ。あとは copilot-instructions.md にルーティングを1行追記すれば完了です。 本記事のポイント： SKILL.md は 500 トークン以内に圧縮 — 190行→58行。モード判定とトークン効率ルールだけ残し、詳細は references/ に分離 description は単一行で書く — description: | の複数行記法は Copilot で読み込まれない。詳細は「 Agent Skillsが動かない？ 」 allowed-tools は Experimental — 仕様にはあるが enforcement 未実装。書いておいて損はないが、過信しない gh CLI のノウハウは共通 — Claude Code と Copilot で変えるのは外側だけ ではまた！ Claude Code で同じことをやるなら「 gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決 」を参照してください。 検証環境 検証日: 2026年3月2〜3日 環境: VS Code + GitHub Copilot（Agent Mode） モデル: claude-sonnet-4.5（Copilot 経由） 参考: VS Code Docs – Agent Skills , agentskills.io Specification 付録：SKILL.md / references/commands.md 全文コピー用 自分のリポジトリに導入するときは、以下のディレクトリ構成でファイルを配置してください。 .github/ ├── copilot-instructions.md ← 末尾にルーティングを追記 ├── skills/ │ └── gh-workflow/ │ ├── SKILL.md ← 下記「SKILL.md 全文」をコピー │ └── references/ │ └── commands.md ← 下記「commands.md 全文」をコピー └── workflows/ └── demo-failure.yml ← テスト用（本記事「テスト用の失敗ワークフロー」参照） .github/skills/gh-workflow/SKILL.md（58行・219語） --- name: gh-workflow description: GitHub Actionsのワークフロー状態確認と失敗ログ分析を行うスキル。gh CLIでCI/CDのログ取得から原因分析まで実行する。Use when: CIが失敗した原因を調べたい、ワークフローの状態を確認したい、PRのチェック結果を見たい。Triggers on: CI確認, Workflow確認, CI失敗, ログ分析, GitHub Actions debug,CI status check, workflow failure, PRチェック, エラーログ, pipeline debug. allowed-tools: Bash(gh:*) Bash(git:*) Bash(jq:*) Read --- # GitHub Actions Workflow Status & Log Analysis gh CLI を使って GitHub Actions の Workflow ステータス確認・ログ分析を行います。 ## Mode Selection ユーザーの指示から以下の4モードを自動判定して実行する。 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | クイックステータス | 「CI確認して」 | `gh run list` | | Run 詳細 | 「Run #123 の詳細」 | `gh run view <run-id>` | | PR チェック | 「PR #42 のチェック」 | `gh pr checks <pr-number>` | | ログ分析 | 「CI失敗してるから見て」 | `gh run view --log --job` | ## Token Efficiency Rules（必須） - `--log` は必ず `--job <job-id>` と併用（全ジョブログは膨大） - `gh run watch` / `gh pr checks --watch` は使用禁止（トークン大量消費） - JSON 出力 + jq で必要なフィールドのみ取得する - Progressive Filtering: 一覧→絞り込み→詳細の順に段階的に情報取得 ## 各モードの実行概要 ### Mode 1: クイックステータス `gh run list --branch $(git branch --show-current) --limit 10` で一覧取得→テンプレート報告。 ### Mode 2: Run 詳細 `gh run view <run-id> --json status,conclusion,jobs,createdAt,updatedAt,headBranch,event` で詳細取得。 ### Mode 3: PR チェック `gh pr checks <pr-number>` でチェック状況取得。PR番号不明時はブランチから自動検出。 ### Mode 4: ログ分析（メイン） 1. `gh run list --status failure` で失敗 Run 特定 2. `gh run view <run-id> --json jobs` で失敗ジョブ特定 3. `gh run view <run-id> --log --job <job-id>` でログ取得（必ず --job 指定） 4. エラー箇所を分析し原因と修正方針を報告 ## 詳細リファレンス JSON 出力パターン、レポートテンプレート、ステータス一覧は `references/commands.md` を参照。 .github/skills/gh-workflow/references/commands.md（79行・266語） # gh-workflow コマンドリファレンス > SKILL.md から参照される詳細情報。Copilot が必要に応じて読み込む。 ## JSON Output Patterns よく使う構造化データ取得パターン: ```bash # Run 一覧を JSON で取得 gh run list --limit 10 --json databaseId,displayTitle,status,conclusion,headBranch,createdAt,event # Run 内のジョブ詳細 gh run view <run-id> --json jobs --jq '.jobs[] | {id: .databaseId, name, status, conclusion, startedAt, completedAt}' # 失敗ジョブのみ抽出 gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' # PR チェックの詳細（JSON） gh pr checks <pr-number> --json name,state,description,detailsUrl ``` ## Report Template 以下のテンプレートを使って結果を報告する。 ### ステータス一覧 ``` ## Workflow Status | # | Workflow | Branch | Status | Conclusion | Triggered | |---|---------|--------|--------|------------|-----------| | 1 | <name> | <branch> | <status> | <conclusion> | <event> | ``` ### 失敗分析 ``` ## Failure Analysis **Run:** #<run-id> - <workflow-name> **Branch:** <branch> **Failed Jobs:** | Job | Error Summary | |-----|--------------| | <job-name> | <error-summary> | **Root Cause:** <分析結果> **Suggested Fix:** <修正方針> ``` ## Status / Conclusion Reference | 値 | 種類 | 意味 | |----|------|------| | `queued` | status | キュー待ち | | `in_progress` | status | 実行中 | | `completed` | status | 完了 | | `waiting` | status | 承認待ち | | `success` | conclusion | 成功 | | `failure` | conclusion | 失敗 | | `cancelled` | conclusion | キャンセル済み | | `skipped` | conclusion | スキップ | | `timed_out` | conclusion | タイムアウト | | `action_required` | conclusion | アクション要求 | | `neutral` | conclusion | 中立（情報のみ） | | `stale` | conclusion | 古い結果 | ## Important Notes - **gh CLI 未認証の場合**: `gh auth status` で認証状態を確認し、未認証ならユーザーに通知 - **リポジトリ外で実行した場合**: エラーをユーザーに通知 - **大量のログ出力**: 必ず `--job` で絞り込み、それでも長い場合は主要なエラー行のみ抽出 - **進行中の Run**: ステータスが `in_progress` の場合、完了を待たずに現在の状態を報告（`watch` は使わない） copilot-instructions.md に追記するルーティング ## Agent Skills Routing | キーワード | スキル | パス | |-----------|--------|------| | CI確認, Workflow, GitHub Actions, ログ分析, CI失敗, pipeline debug | gh-workflow | `.github/skills/gh-workflow/SKILL.md` | 参考リンク 公式ドキュメント VS Code Docs – Agent Skills agentskills.io Specification VS Code Docs – Copilot Customization 関連 Issue microsoft/vscode-copilot-release#14131 — VS Code バリデータが allowed-tools を未認識 関連記事 【2026年版】Agent Skills 入門：SKILL.md の基本から実践まで Claude CodeからGitHub Copilotへ移植したらAgent Skillsが動かない？原因と解決策 gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post GitHub Actions失敗ログ、まだ手動で読む？Copilot Agent Skills で CI デバッグを自動化する実装ガイド first appeared on SIOS Tech Lab .

前回の記事ではSCANOSS GitHub Actionsを使った基本的なコードスキャン自動化の手順 を紹介しました。基本スキャンやポリシーチェック、サブディレクトリスキャンまで確認できたところで、次に気になるのはモノレポ構成への対応です。 scanPath パラメータ は単一の相対パスしか受け付けないため、複数のサブディレクトリを個別にスキャンするにはワークフロー側で工夫が必要です。本記事では、SCANOSS公式の MONOREPO_SETUP.md で推奨されている reusable workflow（ workflow_call ）パターン を使い、PRで変更されたコンポーネントだけを自動スキャンする構成を実際に構築・検証します。 この記事でわかること : モノレポで scanPath が抱える制約と解決策 reusable workflow（ workflow_call ）による共通スキャンワークフローの作り方 パスフィルターとの連携で、変更コンポーネントだけスキャンする構成 構築時のハマりポイント（ permissions の配置）と解決策 前提条件 前回の記事 の内容を理解していること（基本スキャン、 scanPath の動作） GitHubリポジトリにActions実行権限があること リポジトリのSettings > Secretsに SCANOSS_KEY を登録済みであること scanoss/gha-code-scan@v1.5.0 を使用 検証に使用したリポジトリ構成 本記事の検証には、 application/tools/src/ 配下に複数のPythonパッケージを持つモノレポ構成のリポジトリを使用しました。 application/tools/src/ ├── blog_scraper/ # ブログスクレイピングツール（Pythonファイル9個） ├── svg_to_png/ # SVG→PNG変換ツール（Pythonファイル6個） ├── html_to_png/ # HTMLスクリーンショットツール ├── cleanup_articles/ # 記事クリーンアップツール ├── thumbnail_generator/ # サムネイル生成ツール ├── pv_analyzer/ # PV分析ツール └── notion_sync/ # Notion同期ツール このうち blog_scraper と svg_to_png の2ディレクトリをスキャン対象として検証します。 モノレポでのスキャン課題 前回の記事で紹介した scanPath パラメータ を使えば、スキャン対象をサブディレクトリに限定できます。しかし、 scanPath は 単一の相対パスしか受け付けません 。複数パスのカンマ区切りやワイルドカードには対応していません。 # これはできる scanPath: application/tools/src/blog_scraper # これはできない scanPath: application/tools/src/blog_scraper, application/tools/src/svg_to_png モノレポで複数パッケージを個別にスキャンするには、ワークフロー側で対応が必要です。SCANOSS公式の MONOREPO_SETUP.md では、GitHub Actionsの reusable workflow （ workflow_call ）を使ったパターンが推奨されています。 ワークフローの全体構成 作成するファイルは以下の3つです。スキャン対象のコンポーネントが増えるたびにトリガーワークフローを1つ追加します。 .github/workflows/ ├── scanoss-monorepo-base.yml # ベースワークフロー（共通、1つだけ） ├── scanoss-monorepo-blog-scraper.yml # blog_scraper 用トリガー └── scanoss-monorepo-svg-to-png.yml # svg_to_png 用トリガー ファイル 役割 scanoss-monorepo-base.yml workflow_call で呼び出される共通スキャン処理。 scan_path を入力として受け取る scanoss-monorepo-blog-scraper.yml blog_scraper ディレクトリの変更時にベースワークフローを呼び出す scanoss-monorepo-svg-to-png.yml svg_to_png ディレクトリの変更時にベースワークフローを呼び出す ベースワークフローの作成 workflow_call で呼び出される共通のスキャンワークフローです。スキャン対象のパスを inputs.scan_path として受け取ります。 # .github/workflows/scanoss-monorepo-base.yml name: SCANOSS Monorepo Base Scan on: workflow_call: inputs: scan_path: description: 'Directory to scan' required: true type: string jobs: scanoss-scan: name: SCANOSS Scan (${{ inputs.scan_path }}) runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write actions: read steps: - name: Checkout code uses: actions/checkout@v4 - name: Run SCANOSS Code Scan id: scanoss-scan uses: scanoss/gha-code-scan@v1.5.0 with: scanPath: ${{ inputs.scan_path }} api.key: ${{ secrets.SCANOSS_KEY }} permissions を ジョブレベル に配置している点が重要です。トップレベルに置くと startup_failure で失敗します。詳細は後述の「ハマりポイント」で説明します。 コンポーネント別トリガーワークフロー 各コンポーネントにつき1つのワークフローファイルを作成し、ベースワークフローを呼び出します。 # .github/workflows/scanoss-monorepo-blog-scraper.yml name: SCANOSS Scan - blog_scraper on: workflow_dispatch: permissions: contents: write pull-requests: write checks: write actions: read jobs: scan: uses: ./.github/workflows/scanoss-monorepo-base.yml with: scan_path: application/tools/src/blog_scraper secrets: inherit # .github/workflows/scanoss-monorepo-svg-to-png.yml name: SCANOSS Scan - svg_to_png on: workflow_dispatch: permissions: contents: write pull-requests: write checks: write actions: read jobs: scan: uses: ./.github/workflows/scanoss-monorepo-base.yml with: scan_path: application/tools/src/svg_to_png secrets: inherit secrets: inherit でリポジトリのSecretsを呼び出し先に渡します。これにより、ベースワークフロー側で ${{ secrets.SCANOSS_KEY }} が使えます。 まずはこの workflow_dispatch （手動実行）の構成で動作確認した後、次のセクションでパスフィルターを追加します。 パスフィルターとの連携 この構成の最大の利点は、 パスフィルター （ on.pull_request.paths ）との組み合わせです。トリガーワークフローに paths を追加するだけで、 PRで変更されたコンポーネントだけスキャンを発火 させることができます。 # .github/workflows/scanoss-monorepo-blog-scraper.yml name: SCANOSS Scan - blog_scraper on: pull_request: paths: - 'application/tools/src/blog_scraper/**' workflow_dispatch: permissions: contents: write pull-requests: write checks: write actions: read jobs: scan: uses: ./.github/workflows/scanoss-monorepo-base.yml with: scan_path: application/tools/src/blog_scraper secrets: inherit 変更点は on: セクションに pull_request.paths を追加しただけです。 workflow_dispatch も残しておけば、手動実行も引き続き可能です。 この構成により、以下の動作になります。 PRの変更内容 blog_scraper スキャン svg_to_png スキャン blog_scraper/main.py を修正 実行される 実行されない svg_to_png/converter.py を修正 実行されない 実行される 両方を修正 実行される 実行される docs/ のみ修正 実行されない 実行されない モノレポで7つのパッケージがある場合、全パッケージをフルスキャンすると不要なAPI呼び出しと待ち時間が発生します。パスフィルターを使えば、PRで触ったコンポーネントだけをスキャンできるため、 レビューのフィードバックが速くなり、API利用量も抑えられます 。 ハマりポイント：permissionsの配置 構築時に遭遇したハマりポイントを紹介します。 ベースワークフローのpermissionsをトップレベルに置くとstartup_failure 最初にベースワークフローの permissions を ワークフローのトップレベル に配置したところ、呼び出し元のワークフローが startup_failure で即座に失敗しました。 # NG: トップレベルに配置すると startup_failure になる permissions: contents: write pull-requests: write checks: write actions: read jobs: scanoss-scan: ... startup_failure はログが一切生成されないため、原因の特定に手間取ります。 呼び出し元にpermissionsを書かないとstartup_failure ベースワークフローの permissions をジョブレベルに移動しても、呼び出し元ワークフローに permissions がないと同じく startup_failure で失敗します。 reusable workflow では、 呼び出し元のpermissionsが上限 となります。呼び出し元に permissions を書かない場合はリポジトリのデフォルト権限が適用されますが、SCANOSS Code Scan Actionが必要とする権限（ contents: write 、 checks: write 等）が不足する場合に startup_failure が発生します。 解決策 2つの対応を同時に行います。 ベースワークフローの permissions を ジョブレベル に配置する 呼び出し元ワークフローにも permissions を 明示的に記述する 本記事のワークフロー例はすべてこの対応済みの構成です。 実行結果 workflow_dispatch で手動実行した結果です。 ワークフロー ステータス 実行時間 SCANOSS Scan – blog_scraper success 40秒 SCANOSS Scan – svg_to_png success 47秒 各コンポーネントが 独立したワークフローラン として実行されます。GitHub Actions UIでは別々のワークフローとして表示されるため、どのコンポーネントのスキャンが失敗したかが一目でわかります。 コンポーネントの追加方法 新しいパッケージ（例: html_to_png ）をスキャン対象に追加する場合、トリガーワークフローを1つ作成するだけです。ベースワークフローの変更は不要です。 # .github/workflows/scanoss-monorepo-html-to-png.yml name: SCANOSS Scan - html_to_png on: pull_request: paths: - 'application/tools/src/html_to_png/**' workflow_dispatch: permissions: contents: write pull-requests: write checks: write actions: read jobs: scan: uses: ./.github/workflows/scanoss-monorepo-base.yml with: scan_path: application/tools/src/html_to_png secrets: inherit コピーして scan_path と paths を書き換えるだけなので、追加コストは低いです。 まとめ SCANOSS GitHub Actionsのreusable workflowパターンを使い、モノレポでコンポーネント別にスキャンを実行する構成を紹介しました。 項目 ポイント scanPathの制約 単一の相対パスのみ。複数パスやワイルドカードは非対応 公式推奨パターン reusable workflow（ workflow_call ）でベースワークフローを共通化 パスフィルター連携 on.pull_request.paths で変更コンポーネントだけスキャンを発火 permissions ベースワークフローはジョブレベル、呼び出し元にも明示的に記述 コンポーネント追加 トリガーワークフローを1ファイル追加するだけ 参考資料 関連リンク SCANOSS Code Scan Action（GitHub リポジトリ） SCANOSS MONOREPO_SETUP.md（公式モノレポガイド） SCANOSS Code Scan Action（GitHub Marketplace） GitHub Actions: Reusing workflows GitHub Actions: paths フィルター シリーズ記事 SCANOSS CLIでローカルスキャン：インストールからSBOM生成まで SCANOSS GitHub Actionsでコードスキャンを自動化 ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post SCANOSS GitHub Actions モノレポ対応：変更コンポーネントだけスキャンする構成 first appeared on SIOS Tech Lab .

ども！最近 GitHub Actions の Workflow を新規で書くことが増えている龍ちゃんです。Bicep のデプロイパイプラインとか、ブログのビルドチェックとか、地味に CI 周りをいじる機会が多いんですよね。 GitHub Actions のログ確認で作業が途切れる問題 CI をいじってると避けられないのが「CI が落ちたときの確認作業」。 VS Code の GitHub Actions 拡張機能 を入れてれば、どのステップが落ちたかはサイドバーのツリーで確認できます。ただ、拡張機能が教えてくれるのは 「どこが落ちたか」 まで。 「なぜ落ちたのか」をテキストレベルで確認する手段 が足りないんですよね。エラーログの中身を確認しようとすると、ブラウザで GitHub Actions の Run ページを開いて、ジョブを展開して、ログをコピーして…というエディタとブラウザの反復横跳びが発生します。コードの修正を Claude Code と進めてる最中だったら、作業の流れもそこで切れてしまう。 僕がほしかったのは、 「なぜ落ちたか」のログを VS Code 内でテキストとして取得できる仕組み でした。テキストさえ手に入れば、「どう直すか」は Claude Code が分析してくれます（人間もやるよ…）。そこで、 Claude Code の Skills （SKILL.md）と GitHub CLI（ gh コマンド） を組み合わせて、CI のログ取得から分析までを VS Code 内で完結させるスキルを作りました。この記事ではスキルの使い方と作り方を解説します。SKILL.md やデモ用 Workflow の全文は付録に載せているので、すぐ試したい人はそちらもどうぞ。 gh-workflow スキルで何が変わるか /gh-workflow スキルを入れると、Claude Code のチャットで「CI 失敗してるから見て」と打つだけで、失敗した Run の特定 → ログの取得 → 原因分析 → 修正方針の提示まで一気に進みます。SKILL.md に gh CLI の手順を書いておくだけで、Claude がログ取得から分析まで全部やってくれる仕組みです。 なお、 GitHub Actions 拡張機能 は「どこが落ちたか」のツリー確認や YAML 編集支援が得意で、このスキルは「なぜ落ちたか」のログ取得と分析が得意です。置き換えではなく補完関係なので、両方入れておくのがおすすめです。 なぜ gh CLI + スキルを選んだか CI のログを VS Code 内で取得する方法は他にもあります。 GitHub MCP Server の Actions toolset を使えば、 list_workflow_runs や get_job_logs といったツールで同等のことが実現できます。機能的には十分ですが、MCP はツールの戻り値が大きくなりがちで、トークン消費が膨らみやすいというのはわりとあるあるな話です。また、Claude Code の組み込みツール（WebSearch / WebFetch）で GitHub の情報を取りにいくという手もなくはありません。 その上で gh CLI + SKILL.md を選んだのは、僕の環境に合っていたからです。 CLI があるなら CLI で叩きたい。 これは完全に好みの話ですが、サービスが公式 CLI を出しているなら、僕は CLI を選びがちです。MCP だとツールの戻り値をスキル側でコントロールしにくいけど、CLI なら --json や --jq で出力形式を自在に絞れる。SKILL.md に書く手順も Bash コマンドそのままなので、トークン効率のルールをスキル側で設計しやすいのが大きいです プロジェクトで利用実績があった。 Bicep との統合でシークレット登録に gh CLI を使っていたので、認証周りは設定済みだった 認証が gh auth で済む。 devcontainer の postCreateCommand に入れておけば、環境構築時に自動で認証できる SKILL.md 一枚で完結する。 Markdown ファイルを .claude/skills/gh-workflow/SKILL.md に置くだけで動く。Skills は description だけが常時コンテキストに入り、本文は呼び出し時のみロードされるので、普段の会話を圧迫しない 選択肢が複数ある中で gh CLI を選んだのは優劣の話ではなく、自分の環境と好みに合っていたからです。 gh CLI × Claude Code で CI ログを確認する（デモ） ここからは実際のデモです。前提として、 gh CLI がインストール済みで認証が完了している必要があります。 認証方法について : とりあえず試すなら gh auth login でブラウザ認証するのが一番手軽です。ただし OAuth はスコープが広くなりがちなので、運用するなら PAT（Personal Access Token）で最小限のスコープに絞るのがおすすめです。Fine-grained PAT なら対象リポジトリと Actions の読み取り権限だけに制限できます。 # PAT を使った認証 echo "<your-pat>" | gh auth login --with-token このリポジトリにデモ用の Workflow を2つ用意しました。 demo-success.yml : ファイル構造のチェックと YAML バリデーションを行う2ジョブ構成の CI パイプライン demo-failure.yml : 3ジョブ構成で、Test ジョブが意図的に失敗する Workflow（テスト失敗のログを再現） SKILL.md は4モード対応（クイックステータス / Run 詳細 / PR チェック / ログ分析）ですが、今回はデモ用 PR がないので3モードで見ていきます。 クイックステータス — 「CI 確認して」 一番シンプルなモードです。「CI 確認して」と打つと、スキルが gh run list を実行して直近の Workflow 実行状況を取得します。 completed failure Demo - Failure Workflow main workflow_dispatch 22430458939 22s 2026-02-26T06:20:53Z completed success Demo - CI Pipeline main workflow_dispatch 22430440934 21s 2026-02-26T06:20:13Z completed success Demo - CI Pipeline main workflow_dispatch 22430416062 46s 2026-02-26T06:19:12Z completed failure Demo - CI Pipeline main workflow_dispatch 22430368912 48s 2026-02-26T06:17:20Z この生データを、スキルのレポートテンプレートに従って整形します。 ## Workflow Status | # | Workflow | Branch | Status | Conclusion | Triggered | |---|---------|--------|--------|------------|-----------| | 1 | Demo - Failure Workflow | main | completed | failure | workflow_dispatch | | 2 | Demo - CI Pipeline | main | completed | success | workflow_dispatch | | 3 | Demo - CI Pipeline | main | completed | success | workflow_dispatch | | 4 | Demo - CI Pipeline | main | completed | failure | workflow_dispatch | ブラウザを開かなくても、今の CI の状況がチャット上で確認できます。 Run 詳細 — 「この Run の詳細を見て」 成功した Run の中身を確認したいこともあります。「この Run、ジョブの実行時間どのくらいだった？」みたいなとき、Run ID を指定すると gh run view <run-id> で詳細を取得します。 ✓ main Demo - CI Pipeline · 22430440934 Triggered via workflow_dispatch about 4 minutes ago JOBS ✓ Code Check in 6s (ID 64947983939) ✓ Config Validate in 7s (ID 64947996283) ジョブごとの実行時間とステータスが見えるので、Workflow の構成を変えた後に「ちゃんと速くなったか」を確認するのに使ったりします。 ログ分析 — 「CI 失敗してるから見て」 ここがメインの見せ場です。「CI 失敗してるから見て」と打つと、スキルが以下のステップを自動で実行します。 Step 1: 失敗した Run を特定する gh run list --branch main --status failure --limit 5 completed failure Demo - Failure Workflow main workflow_dispatch 22430458939 Step 2: 失敗したジョブを特定する gh run view 22430458939 --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' {"id": 64948053027, "name": "Test"} --json と jq を使って、失敗したジョブだけを抽出しています。全ジョブの情報を取得する必要はなく、失敗したものだけに絞ることでトークンを節約しています。このあたりの工夫は SKILL.md の解説セクションで詳しく説明します。 Step 3: 失敗したジョブのログを取得する gh run view 22430458939 --log --job 64948053027 Test Run integration tests Running integration tests... Test Run integration tests Test Run integration tests FAILED: test_pipeline.py::test_full_pipeline Test Run integration tests AssertionError: Expected status code 200, got 503 Test Run integration tests File: tests/test_pipeline.py, line 42 Test Run integration tests assert response.status_code == 200 Test Run integration tests Test Run integration tests 1 passed, 1 failed in 3.42s Test Run integration tests ##[error]Process completed with exit code 1. --log には必ず --job を付けています。これがないと全ジョブのログが流れてきてトークンを大量に消費するので、失敗したジョブだけに絞るのが鉄則です。 Step 4: Claude が分析してレポートを出す ログを取得したら、Claude がエラー内容を読み取って原因分析と修正方針をまとめます。 ## Failure Analysis **Run:** #22430458939 - Demo - Failure Workflow **Branch:** main **Failed Jobs:** | Job | Error Summary | |-----|--------------| | Test | integration test で AssertionError（期待 200、実際 503） | **Root Cause:** test_pipeline.py の test_full_pipeline テストで、API レスポンスのステータスコードが 期待値 200 に対して 503 (Service Unavailable) を返している。 **Suggested Fix:** - テスト対象の API サーバーが起動しているか確認 - urllib3 のバージョン互換性を確認（requests 2.31.0 は urllib3<3 を要求） 「CI 失敗してるから見て」の一言で、ここまで出てきます。手作業だと Run を探して、ジョブを開いて、ログを読んで…とやっていた調査が全部自動で走り、Claude がそのまま分析に入ります。コードの修正をしていた会話の流れのまま「じゃあこう直しましょう」と続けられるのがポイントです。 このデモではテスト失敗を再現するために作った Workflow を使っています。 demo-failure.yml は echo で pytest 風のエラー出力を再現して exit 1 する構成で、実際のプロジェクトではここに本物のテスト結果が出ます。 SKILL.md の設計 — トークン効率とログ分析の工夫 ここからは「どうやって作ったか」の話です。スキルの実体は .claude/skills/gh-workflow/SKILL.md という Markdown ファイル1枚（全文は付録参照）。自分のプロジェクトでも同じような仕組みを作りたい人向けに、中身をパートごとに見ていきます。 メタデータ（ --- で囲まれたヘッダー部分） --- name: gh-workflow description: | This skill should be used when the user asks to "CI確認して", "Workflow確認", "CIの状態を見て", "ワークフローのログを見て", "CI失敗してるから直して", "PRのチェック状況は", "/gh-workflow", or needs to check GitHub Actions workflow status or analyze CI logs. allowed-tools: Bash, Read --- description にスキルの起動条件を書いておくと、Claude がユーザーの発言を見て自動的にこのスキルを呼び出します。「CI確認して」のような日本語のトリガーも列挙できます。 allowed-tools: Bash, Read で、このスキルが使えるツールを制限しています。 Skills は description だけが常時コンテキストに入っていて、本文はスキルが呼び出されたときにだけロードされるので、普段の会話には影響しません。 モード判定 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | クイックステータス | 「CI確認して」 | `gh run list` | | Run 詳細 | 「Run #123 を見て」 | `gh run view <run-id>` | | PR チェック | 「PR #42 のチェック状況」 | `gh pr checks <pr-number>` | | ログ分析 | 「CI失敗してるから見て」 | `gh run view --log --job` | ユーザーの一言からどのモードを実行するかを、このテーブルで Claude に判断させています。 トークン効率のルール ここが SKILL.md で一番重要なパートです。ただ手順を書くだけなら誰でもできますが、 トークンを無駄遣いしないルール を入れることでスキルの実用性が大きく変わります。 **必ず守ること:** - `--log` は必ず `--job <job-id>` と併用する（全ジョブログは膨大でトークンを大量消費する） - `gh run watch` は使用禁止（リアルタイム出力でトークンを大量消費する） - `gh pr checks --watch` は使用禁止（同上） - JSON 出力 + jq で必要なフィールドのみ取得する --log を --job なしで実行すると、全ジョブのログが一気に流れてきます。CI のログは長くなりがちなので、これをそのままコンテキストに入れるとトークンがあっという間になくなります。 --job で失敗したジョブだけに絞るのが鉄則です。 gh run watch を禁止しているのも同じ理由です。リアルタイム出力がずっと流れ続けるとトークンを食い尽くします。進行中の Run は「今の状態を確認する」だけにして、完了を待ちません。 JSON + jq のルールは、 gh run view --json jobs --jq '.jobs[] | select(.conclusion == "failure")' のように必要なフィールドだけ抽出するためのものです。構造化データで取れるものは構造化データで取ります。 ログ分析モードの設計意図 デモセクションで「何が起きるか」を見ましたが、ここでは「なぜこの設計にしたか」を補足します。SKILL.md に以下の手順を書いておくと、Claude はこの順番で gh CLI を実行します。 ### Step 1: 失敗した Run の特定 gh run list --branch $(git branch --show-current) --status failure --limit 5 ### Step 2: 失敗したジョブの特定 gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' ### Step 3: 失敗ジョブのログ取得 gh run view <run-id> --log --job <job-id> ### Step 4: エラー分析と報告 Run 全体 → 失敗ジョブ → 失敗ジョブのログ、と段階的に絞り込んでいく設計です。最初から全部のログを取るのではなく、必要なものだけに辿り着くようにステップを分けています。この段階的な絞り込みがトークン効率のルールと連動していて、各ステップで情報量を削ることで Claude に渡すデータを最小限にしています。 レポートテンプレート ## Failure Analysis **Run:** #<run-id> - <workflow-name> **Branch:** <branch> **Failed Jobs:** | Job | Error Summary | |-----|--------------| | <job-name> | <error-summary> | **Root Cause:** <分析結果> **Suggested Fix:** <修正方針> 出力フォーマットを統一しておくと、毎回同じ形式で結果が出るので読み方が一定になります。「Root Cause を見て、Suggested Fix を見る」というパターンに慣れれば、確認作業がさらに速くなります。 改善の余地 gh CLI には --log-failed という失敗ステップのみ取得するオプションもあります。SKILL.md にはまだ組み込んでいませんが、 --log --job と組み合わせればさらにログを絞り込めるので、今後の改善候補です。 もう一つ気になっているのが、ログが大量になるケースです。 --job で絞っても、ジョブ自体のログが長いとトークンを圧迫する可能性があります。たとえばログを取得してファイルに保存だけしておくとか、失敗したログをテキストファイルとして書き出す CLI ツールを作るとか、いろいろ模索できそうだなと思っています。まだやってないですけどね。 まとめ ざっくり振り返ると、Before / After はこうなりました。 Before : CI が落ちたら、ブラウザで Run を探して、ジョブを開いて、ログをコピーして、Claude に貼って、文脈を説明する。コードの修正中だったら作業の流れが切れる。 After : 「CI 失敗してるから見て」と打つ。スキルが gh CLI でログを集めて、Claude が分析して修正方針を出す。コードの修正中でも会話の流れはそのまま。 これを実現しているのは、 .claude/skills/gh-workflow/SKILL.md という Markdown ファイル1枚です。特別なインフラもサーバーも不要で、プロジェクトにファイルを1つ追加するだけで動きます。 GitHub Actions 拡張機能 とは補完関係で使うのがおすすめです。YAML の編集支援や「どこが落ちたか」の確認は拡張機能が得意で、「なぜ落ちたか」のログ取得と分析はスキル + Claude が得意です。 SKILL.md は他のプロジェクトでもそのまま使えます。 gh CLI のコマンドを自分のプロジェクトに合わせて書き換えるだけで、同じ仕組みが動きます。トークン効率のルール（ --log には --job 必須、 watch 禁止、JSON + jq で絞り込み）はどのプロジェクトでも共通なので、テンプレートとして参考にしてもらえると思います。 ほなまた〜 シリーズ記事 記事 内容 概要編 — ブラウザなし GitHub 操作を実現する 問題提起と解決策の全体像 この記事（CI 編） 失敗ログの取得から原因分析まで Gist 編 — Gist 操作をチャット1行で完結させる Gist の検索・保存・更新 付録 SKILL.md 全文 .claude/skills/gh-workflow/SKILL.md の内容です。 --- name: gh-workflow description: | This skill should be used when the user asks to "CI確認して", "Workflow確認", "CIの状態を見て", "ワークフローのログを見て", "CI失敗してるから直して", "PRのチェック状況は", "/gh-workflow", or needs to check GitHub Actions workflow status or analyze CI logs. allowed-tools: Bash, Read --- # GitHub Actions Workflow Status & Log Analysis gh CLI を使って GitHub Actions の Workflow ステータス確認・ログ分析を行います。 ## Mode Selection ユーザーの指示から以下の4モードを自動判定して実行する。 | モード | トリガー例 | 主なコマンド | |--------|-----------|-------------| | クイックステータス | 「CI確認して」「Workflowの状態を見て」 | `gh run list` | | Run 詳細 | 「Run #123 を見て」「この Run の詳細」 | `gh run view <run-id>` | | PR チェック | 「PR #42 のチェック状況」「PRのCI」 | `gh pr checks <pr-number>` | | ログ分析 | 「CI失敗してるから見て」「エラーログ確認」 | `gh run view --log --job` | ## Token Efficiency Rules **必ず守ること:** - `--log` は必ず `--job <job-id>` と併用する（全ジョブログは膨大でトークンを大量消費する） - `gh run watch` は使用禁止（リアルタイム出力でトークンを大量消費する） - `gh pr checks --watch` は使用禁止（同上） - JSON 出力 + jq で必要なフィールドのみ取得する --- ## Mode 1: クイックステータス 現在のブランチまたはリポジトリの Workflow 実行状況を一覧表示する。 ### Step 1: Run 一覧の取得 ```bash # 現在のブランチの最新10件 gh run list --branch $(git branch --show-current) --limit 10 # 全ブランチの最新10件（ブランチ指定なし） gh run list --limit 10 ``` ### Step 2: 結果を報告テンプレートで表示 ## Mode 2: Run 詳細 特定の Run ID の詳細情報を取得する。 ### Step 1: Run の詳細取得 ```bash # Run の詳細表示 gh run view <run-id> # JSON で構造化データを取得 gh run view <run-id> --json status,conclusion,jobs,createdAt,updatedAt,headBranch,event ``` ### Step 2: ジョブごとのステータスを整理して報告 ## Mode 3: PR チェック PR に紐づくチェック状況を確認する。 ### Step 1: PR チェックの取得 ```bash # PR のチェック状況 gh pr checks <pr-number> # 現在のブランチの PR チェック（PR 番号不明時） gh pr checks ``` ### Step 2: チェック結果を報告テンプレートで表示 ## Mode 4: ログ分析 失敗した Workflow のログを取得・分析する。 ### Step 1: 失敗した Run の特定 ```bash # 現在のブランチで失敗した Run を検索 gh run list --branch $(git branch --show-current) --status failure --limit 5 ``` ### Step 2: 失敗したジョブの特定 ```bash # Run 内のジョブ一覧を JSON で取得 gh run view <run-id> --json jobs --jq '.jobs[] | {name, status, conclusion}' ``` ### Step 3: 失敗ジョブのログ取得 ```bash # 特定ジョブのログのみ取得（必ず --job を指定） gh run view <run-id> --log --job <job-id> ``` **重要:** `--log` は必ず `--job <job-id>` と併用する。`--job` なしだと全ジョブのログが出力されトークンを大量消費する。 ### Step 4: エラー分析と報告 ログからエラー箇所を特定し、原因と修正方針を報告する。 ## Status / Conclusion Reference | 値 | 種類 | 意味 | |----|------|------| | `queued` | status | キュー待ち | | `in_progress` | status | 実行中 | | `completed` | status | 完了 | | `waiting` | status | 承認待ち | | `success` | conclusion | 成功 | | `failure` | conclusion | 失敗 | | `cancelled` | conclusion | キャンセル済み | | `skipped` | conclusion | スキップ | | `timed_out` | conclusion | タイムアウト | | `action_required` | conclusion | アクション要求 | | `neutral` | conclusion | 中立（情報のみ） | | `stale` | conclusion | 古い結果 | ## JSON Output Patterns よく使う構造化データ取得パターン: ```bash # Run 一覧を JSON で取得 gh run list --limit 10 --json databaseId,displayTitle,status,conclusion,headBranch,createdAt,event # Run 内のジョブ詳細 gh run view <run-id> --json jobs --jq '.jobs[] | {id: .databaseId, name, status, conclusion, startedAt, completedAt}' # 失敗ジョブのみ抽出 gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {id: .databaseId, name}' # PR チェックの詳細（JSON） gh pr checks <pr-number> --json name,state,description,detailsUrl ``` ## Report Template 以下のテンプレートを使って結果を報告する。 ### ステータス一覧 ``` ## Workflow Status | # | Workflow | Branch | Status | Conclusion | Triggered | |---|---------|--------|--------|------------|-----------| | 1 | <name> | <branch> | <status> | <conclusion> | <event> | ``` ### 失敗分析 ``` ## Failure Analysis **Run:** #<run-id> - <workflow-name> **Branch:** <branch> **Failed Jobs:** | Job | Error Summary | |-----|--------------| | <job-name> | <error-summary> | **Root Cause:** <分析結果> **Suggested Fix:** <修正方針> ``` ## Important Notes - **gh CLI 未認証の場合**: `gh auth status` で認証状態を確認し、未認証ならユーザーに通知 - **リポジトリ外で実行した場合**: エラーをユーザーに通知 - **大量のログ出力**: 必ず `--job` で絞り込み、それでも長い場合は主要なエラー行のみ抽出 - **進行中の Run**: ステータスが `in_progress` の場合、完了を待たずに現在の状態を報告（`watch` は使わない） デモ用 Workflow demo-success.yml 2ジョブ構成の CI パイプライン。ファイル構造のチェックと YAML バリデーションを行います。 name: Demo - CI Pipeline on: workflow_dispatch: jobs: check: name: Code Check runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Check file structure run: | echo "Checking project files..." test -f pyproject.toml && echo "OK: pyproject.toml" test -f CLAUDE.md && echo "OK: CLAUDE.md" echo "All checks passed." validate: name: Config Validate runs-on: ubuntu-latest needs: check steps: - name: Checkout repository uses: actions/checkout@v4 - name: Validate YAML configs run: | echo "Validating workflow files..." ls .github/workflows/*.yml | wc -l | xargs -I{} echo "Found {} workflow files" echo "Validation complete." demo-failure.yml 3ジョブ構成で、Test ジョブが意図的に失敗する Workflow。echo で pytest 風のエラー出力を再現しています。 name: Demo - Failure Workflow on: workflow_dispatch: jobs: setup: name: Setup runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Verify environment run: | echo "Environment check..." echo "OS: $(uname -s)" echo "Setup completed." test: name: Test runs-on: ubuntu-latest needs: setup steps: - name: Checkout repository uses: actions/checkout@v4 - name: Run unit tests run: | echo "Running unit tests..." echo "test_fetch_article ... PASSED" echo "test_parse_html ... PASSED" echo "Unit tests passed." - name: Run integration tests run: | echo "Running integration tests..." echo "" echo "FAILED: test_pipeline.py::test_full_pipeline" echo " AssertionError: Expected status code 200, got 503" echo " File: tests/test_pipeline.py, line 42" echo " assert response.status_code == 200" echo "" echo "1 passed, 1 failed in 3.42s" exit 1 deploy: name: Deploy runs-on: ubuntu-latest needs: test steps: - name: Deploy application run: echo "Deploying..." ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決 first appeared on SIOS Tech Lab .