github-traffic

スキル：GitHub トラフィック

GitHub リポジトリのトラフィックデータ（ページビュー、Git クローン、参照元、人気のページ、スターの増加）を取得して分析します。必要に応じて、トレンドチャートを PNG 画像として生成できます。

前提条件：

• gh CLI がインストールされ、認証済みである必要があります
• 対象リポジトリへのプッシュ（書き込み）アクセスが必要です。GitHub の Traffic API は読み取り専用アクセスでは利用できません
• matplotlib は任意です（PNG チャートの生成に使用します。利用できない場合は ASCII にフォールバックします）

---

使用するタイミング

• リポジトリのトラフィック、ページビュー、クローン数、訪問者の参照元について質問された場合
• 時間の経過に伴うトラフィックの傾向（週次、月次、四半期）を確認したい場合
• 共有やドキュメント用のトラフィックレポートチャートを生成したい場合
• 長期的な履歴を作成するため、トラフィックデータを定期的にスナップショットとして保存したい場合

---

重要：GitHub Traffic API の制限事項

GitHub が提供するトラフィックデータは直近 14 日間分のみです。より長い期間（30 日、90 日など）の傾向を追跡するため、スクリプトは取得のたびにローカルの履歴ファイル（~/.github-traffic/<repo>_traffic.json）へデータを保存します。履歴を蓄積するには、定期的なスナップショットが必要です。

推奨：cron ジョブまたは CI スケジュールを設定して、スナップショットコマンドを定期的に実行してください。

# Daily snapshot via cron (no output, just stores data)
0 9 * * * python /path/to/scripts/github_traffic.py owner/repo --snapshot

---

デフォルトのワークフロー

python /path/to/skills/github-traffic/scripts/github_traffic.py <owner/repo>

このコマンドは次の処理を行います。

1. gh api 経由で現在のトラフィックデータを取得します
2. 履歴追跡用のスナップショットを ~/.github-traffic/ に保存します
3. 書式付きの概要（ビュー、クローン、参照元、人気のページ）を表示します

---

チャートの生成

# Generate PNG trend chart (last 30 days, default)
python .../github_traffic.py owner/repo --chart

# Last 7 days
python .../github_traffic.py owner/repo --chart --days 7

# Last 90 days (needs accumulated history)
python .../github_traffic.py owner/repo --chart --days 90

# ASCII chart (no matplotlib needed)
python .../github_traffic.py owner/repo --ascii

PNG チャートには、最大 3 つのパネルが含まれます。

1. ページビュー — 合計ビュー数とユニーク訪問者数（面グラフ）
2. Git クローン — 合計クローン数とユニーククローン実行者数（棒グラフ＋折れ線グラフ）
3. スターの増加 — 時間の経過に伴うスター数（複数のスナップショットがある場合に表示される折れ線グラフ）

---

スクリプトのオプション

フラグ	デフォルト	説明
repo（位置引数）	必須	owner/name 形式のリポジトリ
--chart	オフ	トレンドチャートを PNG で生成します
--ascii	オフ	ASCII の棒グラフ出力を強制します
--days	30	チャートに含める日数
--history-dir	~/.github-traffic/	履歴データの保存先ディレクトリ
--output	<repo>_traffic.png	チャート画像の出力先
--snapshot	オフ	データの取得と保存のみを行います（表示なし）

---

例

# Quick traffic summary
python .../github_traffic.py zilliztech/memsearch

# Weekly trend chart
python .../github_traffic.py zilliztech/memsearch --chart --days 7

# Monthly trend chart, custom output path
python .../github_traffic.py zilliztech/memsearch --chart --days 30 --output ./reports/traffic.png

# Just store a snapshot (for cron jobs)
python .../github_traffic.py zilliztech/memsearch --snapshot

# ASCII chart when matplotlib is not available
python .../github_traffic.py zilliztech/memsearch --ascii --days 14

---

履歴と長期追跡

実行するたびに、現在の 14 日間のデータが ~/.github-traffic/<owner>_<repo>_traffic.json の永続 JSON ファイルに統合されます。このファイルには次の情報が含まれます。

• 日別ビュー：日付 → {ビュー数、ユニーク数}
• 日別クローン：日付 → {クローン数、ユニーク数}
• スターのスナップショット：日付 → スター数
• 取得メタデータ：タイムスタンプ、14 日間の合計、スター数、フォーク数

有意義な 30 日／90 日のチャートを作成するには、少なくとも 14 日ごとにスクリプトを実行してください（毎日の実行が理想的です）。14 日を超える間隔が空くと、チャート上ではデータ欠損として表示されます。

---

権限

GitHub Traffic API の利用には、リポジトリへのプッシュアクセスが必要です。つまり、以下のとおりです。

• リポジトリのオーナーと管理者：完全なアクセス権
• 書き込み／管理者ロールを持つコラボレーター：完全なアクセス権
• 読み取り専用ユーザーとフォークしたユーザー：アクセス不可（API は 403 を返します）

権限エラーが発生した場合は、gh auth status を確認し、トークンに repo スコープがあることを確認してください。

---

トラブルシューティング

問題	解決方法
「Must have push access」エラー	リポジトリへの書き込みアクセスが必要です。gh auth status を確認してください。
チャートに 14 日分しか表示されない	GitHub が提供するデータは 14 日間分のみです。履歴を蓄積するため、--snapshot を定期的に実行してください。
matplotlib が見つからない	pip install matplotlib でインストールしてください。または、テキストベースのチャートには --ascii を使用してください。
一部の日付のデータがない	GitHub はトラフィックがゼロの日を報告しない場合があります。こうした欠損は通常のものです。