ドキュメント

はじめに

cacika は macOS で動く GitHub 生産性レポートツールです。GitHub リポジトリの PR 数・コミット数・インシデント率を時系列で集計し、チームや個人のパフォーマンスを スタンドアローン HTML レポートとして出力します。

必要な GitHub スコープ

セットアップ

github_owner: "your-org"

github_repositories:
  - name: "your-repo"
    base_branch: "main"
    incident_label: "incident"

github_members:
  - "alice"
  - "bob"

config.yaml リファレンス

config.yaml はアプリの設定ファイルです。集計対象のリポジトリ・メンバー・チームを定義します。 以下に全フィールドを記載した完全なサンプルを示します。

完全サンプル

# 必須 ──────────────────────────────────────────────────
# GitHub の Organization 名またはユーザー名
github_owner: "your-org"

# 集計対象のリポジトリ（複数指定可）
github_repositories:
  - name: "backend-repo"
    base_branch: "main"
    exclude_label: "dependencies"        # このラベルの PR を除外
    incident_label: "incident"           # インシデントとして扱うラベル
    exclude_prefix_pr_titles:            # このプレフィックスで始まる PR を除外
      - "Revert"

  - name: "frontend-repo"
    base_branch: "main"
    exclude_label: "dependencies"
    incident_label: "hotfix"

# オプション ──────────────────────────────────────────────
# 追跡対象のメンバー
github_members:
  - "alice"
  - "bob"
  - "charlie"

# チーム構成（Teams ページで使用）
team_members:
  backend:
    github_members:
      - "alice"
      - "bob"
  frontend:
    github_members:
      - "charlie"

# API レート制限設定
github_api_rate_limit:
  default_max_get_pr_count: 500          # PR 取得の上限（デフォルト: 500）
  default_max_commit_count: 1000         # コミット取得の上限（デフォルト: 1000）
  # リポジトリ別に個別設定することも可能
  # max_get_pr_counts:
  #   backend-repo: 1000
  # max_commit_counts:
  #   backend-repo: 2000

# リリース進行レポート設定（GitHub Project 連携）
release_progress:
  github_project_number: 1              # GitHub Project V2 の番号
  github_project_owner: "your-org"      # Project 所有者名
  project_owner_type: "org"             # "org" または "user"
  spec_repositories:                    # 仕様 issue のリポジトリ
    - "spec-repo"
  dev_repositories:                     # 開発 issue のリポジトリ
    - "backend-repo"
    - "frontend-repo"
  test_repositories:                    # テスト issue のリポジトリ
    - name: "test-repo"
      exclude_prefix_issue_titles:      # 除外する issue タイトルのプレフィックス
        - "【QA環境】"

# インシデントトレンドチャート設定
incidents_trend:
  incident_display_scale: 10            # インシデント数の表示倍率（PR 数と差が大きい場合に設定）

github_repositories のフィールド

team_members の構造

任意のチーム名をキーとして、各チームに所属するメンバーを指定します。 チームを設定するとレポートの Teams ページ が有効になります。

team_members:
  backend:                              # チーム名（任意）
    github_members:
      - "alice"
      - "bob"
  frontend:
    github_members:
      - "charlie"

github_api_rate_limit のフィールド

大規模なリポジトリで取得に時間がかかる場合に上限を引き上げます。通常はデフォルト値で問題ありません。

release_progress のフィールド

GitHub Project V2 と連携してリリース進行レポートを生成する機能です。 仕様 issue → 開発 issue → テスト issue の階層をたどり、各フェーズの所要日数を集計します。

incidents_trend のフィールド

インシデント数が PR 数に比べて非常に少ない場合、グラフ上でインシデントのラインが見づらくなります。 incident_display_scale を設定すると表示上の倍率を調整できます（ツールチップには実数値と倍率後の値の両方が表示されます）。

incidents_trend:
  incident_display_scale: 10    # インシデント数 × 10 でグラフに表示（デフォルト: 1）

自動スケジュール

設定 → スケジュール タブで、データの自動取得スケジュールを設定できます。 バックグラウンドで定期的に GitHub からデータを収集します。

データ管理

収集したデータはローカルの SQLite データベースに保存されます。 JSON 形式でのバックアップ・復元と、データの完全削除をサポートしています。

レポートの見方

生成された HTML ファイルはスタンドアローンで動作します。サーバー不要でブラウザで開くだけで閲覧でき、 日次・週次・月次・四半期など集計粒度を切り替えられます。

集計粒度