ドキュメント

はじめに

cacika は macOS で動く GitHub の集計ツールです。リポジトリの PR 数・コミット数・インシデント率を時系列で数え、スタンドアローンの HTML レポートとして出力します。数えられるのはアウトプットの量だけで、 その成果や生産性を測るものではありません（注意書き）。

必要な GitHub スコープ

セットアップ

インストールから最初のレポートが出るまでの手順です。順番どおりに進めれば 5 ステップで終わります。 cacika はメニューバーに常駐するアプリで、操作はすべて 画面右上のメニューバーアイコン（または Dock アイコンの右クリック）から開きます。

1

アプリを起動する

購入後にダウンロードした cacika.app を Applications フォルダへ移動して起動します。起動するとメニューバーに cacika のアイコンが追加されます。

初回起動時は ライセンス認証 のウィンドウが開きます。 購入時に発行されたライセンスキーを貼り付けて 「認証する」 を押してください。

認証が終わると、メニューの 「設定」 と「レポート出力」 が使えるようになります。 まだライセンスを持っていない場合は、同じ画面の「ライセンスキーを購入する」から購入できます。

ライセンスの確認・解除は、あとからメニューの「ライセンス情報を確認」で開けます（ライセンス管理）。

2

GitHub Token を登録する

メニューバーアイコン → 設定 を開き、一般 タブに GitHub fine-grained PAT を入力して「保存」 を押します。 Token が未登録のままだと、他のタブは設定できません。

Token は 暗号化されてローカルに保存されるため、 設定ファイルに平文で記載する必要はありません。必要なスコープははじめに を参照してください。

Token はマシン固有情報から生成したキーで暗号化されます。別のマシンに移行する際は Token を再登録してください。

3

config.yaml を作成する

設定の コンフィグ タブを開きます。初期状態では「config.yaml が設定されていません」 と表示され、 集計対象が何も決まっていない状態です。ここに読み込ませるconfig.yaml を、まずローカルで作成します。

以下のテンプレートを参考に作成してください。最低限必要なのはgithub_owner（Organization 名またはユーザー名）と、 集計対象を並べる github_repositories の 2 つです。 ファイル名は config.yaml、置き場所はどこでも構いません。

github_owner: "your-org"

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

github_members:
  - "alice"
  - "bob"

チーム別の集計を出したいときはteam_members、 リリース進行レポートを使いたいときはrelease_progress を追加します。 全フィールドの説明と完全サンプルはconfig.yaml リファレンス にあります （アプリのコンフィグタブにある ? アイコンからも開けます）。

4

config.yaml をインポートする

設定の コンフィグ タブで「import」 を押し、作成したconfig.yaml を選択します。 読み込みに成功すると、下のように中身がそのまま表示され、どの設定が有効になっているかを確認できます。

設定を変えたいときは、手元のconfig.yaml を編集して もう一度 「import」 すれば上書きされます。 いま読み込まれている設定をファイルとして取り出したいときは「export」 を使います。

ここまででセットアップは完了です。あとはデータを取るだけです。

5

データを取得してレポートを生成する

メニューバーアイコン → レポート出力 を開きます。 まだ一度もデータを取得していない状態では、右側の実行履歴に「まだデータを取得していません」 と表示されます。

データを取得する

左下の 「取得範囲」 に、取得を開始したい日付を設定します （日付を押すとカレンダーが開きます）。この日付から現在までが集計の対象範囲です。

範囲を決めたら 「最新のデータを取得」 を押すと、GitHub からのデータ取得が始まります。 取得中はボタンが「データ取得中…」に変わり、その下に進行中のログが流れます。 完了すると右側の 実行履歴 に結果が並びます。

2 回目以降は前回の取得日が初期値として入るので、そのまま押せば差分だけを取り込めます。 初回や範囲が広いときは GitHub API の呼び出し数が増えるぶん時間がかかります。

レポートを出力する

取得が完了したら、左上の 「レポートを出力」 を押します。 生成が終わると保存ダイアログが開くので、保存先を選んでreport.html をダウンロードします。

出力されるのは 1 枚で完結する HTML ファイルです。サーバーは不要で、ブラウザで開くだけで閲覧できます。 中身の読み方は レポートの見方 を参照してください。

毎回手で取得するのが面倒なときは、設定の スケジュール タブで バックグラウンドの自動取得を有効にできます（自動スケジュール）。

config.yaml リファレンス

config.yaml はアプリの集計設定ファイルです。集計対象のリポジトリ・メンバー・チームを定義します。 アプリの 設定 → コンフィグ タブから import して読み込みます。

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

# 集計対象のリポジトリ（1 件以上）
github_repositories:
  - name: "backend-repo"
    base_branch: "main"
    exclude_label: "dependencies"        # このラベルが付いた PR を集計から除外
    incident_label: "incident"           # インシデントとして扱うラベル
    exclude_prefix_pr_titles:            # このプレフィックスで始まる PR を除外
      - "Revert"
      - "Reapply"
    qafix_labels:                        # リリーステストの修正のPRを別集計したいときのラベル
      - "qafix"

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

# ── 任意 ─────────────────────────────────────────────
# 集計対象のメンバー（省略すると PR / コミットに現れたメンバーが対象）
github_members:
  - "alice"
  - "bob"
  - "charlie"

# チーム構成。設定するとレポートの Teams ページが有効になる
team_members:
  backend:
    github_members:
      - "alice"
      - "bob"
  frontend:
    github_members:
      - "charlie"

# GitHub 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 V2 連携）
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 タイトルのプレフィックス
        - "[dev]"

何を設定すると、どのレポートに出るか

config.yaml の設定は、レポートの 3 つの集計に対応します。 「この集計で使うフィールドを見る」を押すと、下のフィールド一覧をその集計で使う項目だけに絞り込みます。

メンバー、チームの PR マージの集計

ベースブランチにマージされた PR とコミットを、メンバー別・チーム別に数えます。除外ラベルや除外プレフィックスで、集計に入れない PR を決められます。

この集計で使うフィールドを見る

詳しい集計の仕組みを表示詳しい集計の仕組みを閉じる

1. 1

   対象の PR を集める

   github_repositories の各リポジトリについて、base_branch にマージ済みの PR を取得します。期間の判定に使うのは マージ日時 で、作成日ではありません。まだマージされていない PR は数えません。

2. 2

   二段階マージをほどく

   中間ブランチにいったんマージし、そのブランチごと base_branch に入れている場合、束ねている統合 PR は数えず、中に入っていた個々の PR に置き換えて数えます。逆に base_branch 自体を別ブランチへ流す PR（head がベースブランチ）は、作業が入ってくる PR ではないので除外します。

3. 3

   除外ルールを適用する

   exclude_label が付いた PR、exclude_prefix_pr_titles のいずれかで始まるタイトルの PR（大文字小文字は区別しません）、qafix_labels に該当する差し戻しの PR は、通常の集計から外します。

4. 4

   PR とコミットを数える

   PR は作成者ごとに 1 件として数えます。コミットは、期間内の対象 PR にぶら下がるコミットだけを、コミットの作成者ごとに数えます。PR を通っていないコミットは数に入りません。

5. 5

   チームと 1 人あたりを出す

   team_members に書いたメンバーの数を合算してチームの数にします。1 人あたりは 合計 ÷ メンバー数 で、小数第 2 位までを切り捨てます。

数えているのはマージされた PR とそのコミットの件数だけです。変更行数・レビュー時間・難易度は見ていません。

障害発生の集計

インシデントラベルが付いた PR が全体の何割かを、期間ごとに出します。ラベル名はリポジトリごとに指定できます。

この集計で使うフィールドを見る

詳しい集計の仕組みを表示詳しい集計の仕組みを閉じる

1. 1

   母数は PR の集計と同じ

   上の PR 集計と同じルール（マージ日時・二段階マージ・除外ラベル・除外プレフィックス）で絞り込んだ PR が、そのまま割合の分母になります。

2. 2

   障害の PR を見分ける

   リポジトリごとに指定した incident_label が付いている PR を障害として数えます。見るのは PR に付いたラベルだけで、issue のラベルは見ません。

3. 3

   メンバー・チーム・推移

   同じ計算をメンバー別とチーム別でも行います。推移のグラフは、選んだ期間を起点に直近 8 期間ぶんを並べます。

ラベルの付け忘れはそのまま数字に出ます。ラベル運用が揃っていないチーム同士の比較には向きません。

リリース進行の集計

GitHub Project V2 の仕様 issue から、開発 issue・開発 PR・テスト issue の階層をたどり、企画から開発・テストまでの所要日数を出します。

この集計で使うフィールドを見る

詳しい集計の仕組みを表示詳しい集計の仕組みを閉じる

1. 1

   基本的な設計

   この機能は仕様、開発、テストをすべてGitHubのissueを使用している前提でのみ集計できる機能なのでご注意ください。

2. 2

   issue の階層をたどる

   仕様 issue のタイムラインの相互参照から dev_repositories の開発 issue（と、その sub-issue を最大 50 件）を拾い、その issue を閉じた PR、さらに PR のタイムラインから test_repositories のテスト issue へたどります。exclude_prefix_issue_titles で始まるテスト issue は除きます。

3. 3

   日数を出す

   どの指標も issue の作成日時からクローズ日時までの差を日数（小数）で出します。企画開始〜リリースは仕様 issue の作成→クローズ、要件定義は仕様 issue の作成→最初の開発 issue の作成、開発とテストの全体期間は「いちばん古い作成日→いちばん新しいクローズ日」、個々の期間はその issue 自身の作成→クローズです。

4. 4

   終わっていないものの扱い

   仕様 issue が open のままなら「進行中」として、平均の計算から外します。開発 issue・テスト issue が 1 つでも open だと、その全体期間は出しません（空欄になります）。

5. 5

   まとめかた

   完了した仕様 issue について平均・最大・最小を出します。一覧は仕様 issue の作成日を基準に、今月末で終わる 3 ヶ月ごとの区切りでまとめます。

出るのは日数だけです。長い / 短いが良し悪しを表すわけではなく、issue の切り方や運用の違いでも簡単に変わります。

フィールド一覧

全 25 フィールドです。フィールド名・説明・表示画面の部分一致で絞り込めます。

自動スケジュール

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

データ管理

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

ライセンス管理

ライセンスキーは 1 台の Mac に登録して使います。 買い替えや故障で別の Mac に移すときは、先に元の Mac の登録を解除してください。

レポートの見方

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

集計粒度