gh CLI × Claude Code で GitHub Actions 失敗ログをチャットで即解決

---
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` は使わない）

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."

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..."