commit-report-tool/.claude/skills/github-api/SKILL.md

name	description	allowed-tools
github-api	GitHub REST APIの使い方。コミット取得、差分取得、リポジトリ情報取得に使用。	Bash(node:*), Bash(gh:*)

GitHub API ガイド

GitHub REST API の使用方法を説明します。

⚠️ 重要: コミット取得はスクリプトを使用

前日のコミット取得は必ず以下のスクリプトを使用してください。 日付計算を手動で行わないでください。

全ブランチ一括取得（推奨）

# ⚠️ 必ず --output オプションを使用（シェルリダイレクトは使わない）
node .claude/skills/github-api/scripts/get-all-branch-commits.js <owner> <repo> --output /tmp/all-commits.json

全ブランチのコミットを一括で取得します。daily-reportではこちらを使用してください。

重要: --output オプションを使用してファイルに直接書き込んでください。 シェルリダイレクト（> file）は stdout/stderr が混在する問題があります。

最適化版: GraphQLで最近アクティブなブランチのみを抽出してからコミット取得。 309ブランチ → 約20ブランチに絞り込み（約90%のAPI呼び出し削減）。

環境変数 ACTIVE_DAYS でアクティブ判定期間を変更可能（デフォルト: 7日）。

パスフィルタリング

node .claude/skills/github-api/scripts/filter-commits-by-path.js \
  --owner <owner> --repo <repo> --paths "app/,web/,supabase/"

get-all-branch-commits.js の出力を受け取り、指定パスに関連するコミットのみを抽出します。 各コミットの変更ファイルを GitHub API で取得し、パスマッチングを行います。

⚠️ 重要: コミットのパスフィルタリングは必ずこのスクリプトを使用してください。 アドホックなフィルタリングコードは全件処理を保証できません。

引数	必須	説明
--input <file>	No	入力ファイル（省略時stdin）
--owner <name>	Yes	リポジトリオーナー
--repo <name>	Yes	リポジトリ名
--paths <list>	Yes	カンマ区切りパス（例: "app/,web/"）
--concurrency <n>	No	並列数（デフォルト: 5）

使用例:

# パイプライン使用
node .claude/skills/github-api/scripts/get-all-branch-commits.js owner repo \
  | node .claude/skills/github-api/scripts/filter-commits-by-path.js \
      --owner owner --repo repo --paths "app/,web/,supabase/"

# ファイル入力
node .claude/skills/github-api/scripts/filter-commits-by-path.js \
  --input /tmp/commits.json \
  --owner owner --repo repo --paths "app/,web/,supabase/"

出力形式は入力と同じ構造 + 追加フィールド:

• metadata.filter_paths: フィルタ対象パス
• metadata.original_commits: フィルタ前のコミット数
• metadata.filtered_commits: フィルタ後のコミット数
• 各コミットに matched_files フィールド（マッチしたファイル情報）

単一ブランチ取得

node .claude/skills/github-api/scripts/get-commits.js <owner> <repo> [branch]

出力形式

スクリプトは正規化されたJSONを出力します。jqでの追加処理は不要です。

全ブランチ一括取得の出力

{
  "metadata": {
    "target_date": "2026-01-23",
    "start_utc": "2026-01-22T15:00:00Z",
    "end_utc": "2026-01-23T14:59:59Z",
    "total_branches": 308,
    "checked_branches": 18,
    "active_branches": 6,
    "total_commits": 31,
    "default_branch": "main",
    "active_days_filter": 7,
    "failed_branches": 0,
    "has_errors": false
  },
  "branches": {
    "main": {
      "commits": [...],
      "is_default": true
    },
    "feature-branch": {
      "commits": [...],
      "is_default": false
    }
  }
}

フィールド	説明
metadata.target_date	対象日（JST）
metadata.total_branches	全ブランチ数
metadata.checked_branches	チェックしたブランチ数（最適化後）
metadata.active_branches	コミットがあるブランチ数
metadata.default_branch	デフォルトブランチ名
metadata.active_days_filter	アクティブ判定期間（日数）
metadata.failed_branches	取得失敗したブランチ数
metadata.has_errors	エラーがあったかどうか
branches[name].commits	コミット配列
branches[name].is_default	デフォルトブランチかどうか
errors	失敗したブランチの詳細（エラー時のみ）

エラーハンドリング（自動リカバリ）

スクリプトは以下の自動リカバリ機能を持ちます：

1. 個別リトライ: 各ブランチ取得は最大3回リトライ（指数バックオフ: 1秒、2秒、4秒）
2. 一括再試行: 1回目のループで失敗したブランチは、10秒後にまとめて再試行
3. 確実な失敗検出: 再試行でも失敗した場合、exit 1 で終了

動作フロー:

1回目のループ (308ブランチ)
  → 各ブランチ最大3回リトライ
  → 失敗: 2ブランチ

10秒待機

再試行ループ (2ブランチ)
  → 各ブランチ最大3回リトライ
  → 失敗: 0ブランチ → 正常終了 (exit 0)
  → 失敗: 1ブランチ以上 → 異常終了 (exit 1)

GitHub Actionsでの動作:

• exit 1 → ワークフロー失敗として記録
• 「Re-run jobs」で再実行可能
• 一時的なAPI不安定は自動リカバリで解決する場合が多い

単一ブランチ取得の出力

保証される項目

フィールド	説明
sha	コミットハッシュ
message	コミットメッセージ
date	コミット日時（ISO 8601）
author.login	ユーザー名（必ず存在）
author.avatar_url	アバターURL（必ず存在）
html_url	GitHubへのリンク

出力例

[
  {
    "sha": "abc1234567890",
    "message": "コミットメッセージ",
    "date": "2026-01-19T10:00:00Z",
    "author": {
      "login": "username",
      "avatar_url": "https://avatars.githubusercontent.com/u/123?v=4"
    },
    "html_url": "https://github.com/..."
  }
]

フォールバック

GitHub APIで author: null の場合（メールがGitHubに紐付いていない）:

• login: コミッター名を使用
• avatar_url: Gravatar identicon（メールハッシュから生成）

フォールバック発生時は標準エラーにログ出力:

[Avatar] フォールバック: Unknown User (8cca2ef)

例

# your-username/your-web-app の main ブランチ
node .claude/skills/github-api/scripts/get-commits.js your-username your-web-app main

# 出力例（標準エラー）:
# === 検索期間 ===
# 対象日(JST): 2026-01-18
# 開始(UTC): 2026-01-17T15:00:00Z
# 終了(UTC): 2026-01-18T14:59:59Z
# ブランチ: main
# ================

環境変数

• GH_TOKEN: GitHub API認証トークン（必須）
• TARGET_DATE: 対象日を指定（省略時は前日JST）形式: YYYY-MM-DD

禁止事項

❌ date -u や date -d で日付計算を手動実行 ❌ since=$TODAY のような変数を自分で定義 ❌ タイムゾーン変換を手動で計算

理由

日付計算は以下の問題が起きやすい：

• date -u はUTCの「当日」を返す（JSTではない）
• macOS と Linux で date のオプションが異なる
• タイムゾーン変換の計算ミス

スクリプトはテスト済みで、毎回同じ結果を保証します。

---

認証

環境変数 GH_TOKEN を使用：

curl -H "Authorization: Bearer $GH_TOKEN" \
     -H "Accept: application/vnd.github+json" \
     -H "X-GitHub-Api-Version: 2022-11-28" \
     "https://api.github.com/..."

エンドポイント

コミット一覧取得

GET /repos/{owner}/{repo}/commits

パラメータ:

• since: ISO 8601形式の日時（この日時以降のコミット）
• author: 作者でフィルタ

レスポンス:

[
  {
    "sha": "abc1234567890",
    "commit": {
      "message": "コミットメッセージ",
      "author": {
        "name": "Author Name",
        "date": "2025-01-01T12:00:00Z"
      }
    },
    "author": {
      "login": "github-username",
      "id": 1234567,
      "avatar_url": "https://avatars.githubusercontent.com/u/1234567?v=4"
    },
    "html_url": "https://github.com/..."
  }
]

⚠️ 図解で使用する重要フィールド

HTML図解を生成する際、以下のフィールドを必ずAPIレスポンスから取得すること：

フィールド	用途	注意
author.login	ユーザー名表示	サンプルの値をコピーしない
author.avatar_url	アバター画像	必ずAPIから取得
commit.author.date	日時表示	ISO 8601形式

禁止事項:

• サンプルHTMLのURLをそのまま使用
• 架空のavatar_urlを生成
• 他のユーザーのavatar_urlを流用

コミット詳細取得（差分含む）

GET /repos/{owner}/{repo}/commits/{sha}

レスポンス:

{
  "sha": "abc1234567890",
  "files": [
    {
      "filename": "src/index.ts",
      "status": "modified",
      "additions": 10,
      "deletions": 5,
      "patch": "@@ -1,5 +1,10 @@\n-old\n+new"
    }
  ],
  "stats": {
    "additions": 10,
    "deletions": 5,
    "total": 15
  }
}

リポジトリ情報取得

GET /repos/{owner}/{repo}

レスポンス:

{
  "name": "repo-name",
  "description": "Repository description",
  "language": "TypeScript",
  "default_branch": "main"
}

ブランチ一覧取得

GET /repos/{owner}/{repo}/branches

パラメータ:

• per_page: 1ページあたりの件数（最大100）

例:

curl -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/owner/repo/branches?per_page=100"

レスポンス:

[
  {
    "name": "main",
    "commit": {
      "sha": "abc1234567890",
      "url": "https://api.github.com/repos/owner/repo/commits/abc1234567890"
    },
    "protected": true
  },
  {
    "name": "feature/video-player",
    "commit": {
      "sha": "def5678901234",
      "url": "https://api.github.com/repos/owner/repo/commits/def5678901234"
    },
    "protected": false
  }
]

ブランチ別コミット取得

特定ブランチのコミットを取得するには sha パラメータにブランチ名を指定:

GET /repos/{owner}/{repo}/commits?sha={branch_name}&since={date}

⚠️ 日付計算は必ずスクリプトを使用してください（上記「禁止事項」参照）。

ブランチの累計コミット取得

ブランチの履歴を把握するため、直近N件のコミットを取得:

# 直近30件のコミットを取得（ブランチの概要把握用）
curl -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/owner/repo/commits?sha=feature/video-player&per_page=30"

用途:

• ブランチの目的をAIで要約
• 累計コミット数の表示
• ブランチ開始日の特定（最古のコミット日時）

エラーハンドリング

ステータス	意味	対処
401	認証エラー	GH_TOKEN を確認
403	レート制限	待機または認証確認
404	リポジトリ不在	owner/repo を確認

レート制限

• 認証済み: 5000リクエスト/時
• X-RateLimit-Remaining ヘッダーで残り確認可能