GitHub Projects の設定ガイド

GitHub Projects V2 を Code Tempo で活用するための設定手順と推奨構成を説明します。正しく設定することで、サイクルタイム分析、バーンダウンチャート、ベロシティ比較などの機能を最大限に活用できます。

GitHub Projects V2 と Code Tempo

Code Tempo は GitHub Projects V2 のデータを読み取り、プロジェクトの進捗や効率を分析します。以下の分析機能が GitHub Projects V2 のデータに依存しています。

進捗追跡

プロジェクト全体の完了率やステータス別の分布を可視化します。

バーンダウン/バーンアップ

時系列でプロジェクトの進捗を追跡し、完了予測を表示します。

サイクルタイム分析

アイテムがステータスを通過する時間を計測し、ボトルネックを特定します。

チームベロシティ比較

イテレーション（スプリント）ごとの完了アイテム数を比較します。

前提条件

Code Tempo で GitHub Projects を分析するには、以下の条件が必要です。

GitHub Projects V2 を使用していること（クラシック Projects は非対応）
OAuth 認証で read:project スコープが許可されていること
Code Tempo のプロジェクト設定で分析対象のプロジェクトが登録されていること

プロジェクトの登録手順

プロジェクト設定ページを開く

Code Tempo にログインし、Settings → Projects ページに移動します。

プロジェクトを選択

登録可能なプロジェクト一覧から、分析したいプロジェクトにチェックを入れます。個人・Organization 両方のプロジェクトが表示されます。

ダッシュボードで確認

ダッシュボードの「Projects」タブに移動すると、登録したプロジェクトの分析結果が表示されます。

プロジェクト分析は Standard プランの機能です。Free プランではプロジェクト数に制限があります。

推奨するボード構成

Code Tempo の分析精度を最大化するために、以下の構成を推奨します。

ステータスフィールド

GitHub Projects V2 にはデフォルトで「Status」フィールドがあります。サイクルタイム分析やバーンダウンチャートは、このステータスの変遷をもとに計算されます。

推奨ステータス構成

Todo → In Progress → In Review → Done

Todo: 未着手のアイテム
In Progress: 作業中のアイテム
In Review: レビュー待ちのアイテム（任意）
Done: 完了したアイテム

ステータスの名前は自由に変更できます。Code Tempo はフィールドの値の変遷を追跡するため、名前に依存しません。

Iteration フィールド（ベロシティ比較に必須）

チームベロシティ比較を利用するには、GitHub Projects V2 にIteration フィールドの追加が必要です。

Projects の Settings を開く

GitHub Projects のページ右上の「…」メニューから Settings を選択します。

Custom fields で Iteration を追加

「Custom fields」セクションで「New field」をクリックし、Field type を「Iteration」に設定します。

イテレーション期間を設定

スプリントの期間（例: 2 週間）と開始日を設定します。

各アイテムに Iteration を割り当て

Issue や PR を対応するイテレーション（スプリント）に割り当てます。

Iteration フィールドがないプロジェクトでは、ベロシティ比較機能が利用できません（エラーになります）。

各分析機能に必要な設定

機能ごとに必要な GitHub Projects の設定をまとめます。

分析機能	必須設定	推奨設定
進捗追跡	Status フィールド	—
バーンダウン	Status フィールド	Issue の Close
サイクルタイム	Status フィールド	ステータスの段階的な変更
ベロシティ比較	Iteration フィールド	Assignee の設定
チーム分析	Assignee	Iteration フィールド

ベロシティの計算方法

ベロシティは以下のルールで計算されます。

完了アイテム数でカウント

Issue は closedAt、PR は mergedAt の有無で完了判定。Open のままのアイテムはベロシティ 0 として扱われます。

Iteration ごとに集計

各イテレーション期間内に完了したアイテム数を集計します。Iteration 未設定のアイテムは除外されます。

メンバー別に比較可能

Assignee が設定されたアイテムはメンバー別に集計。未設定は「unassigned」として一括集計されます。

Standard プランが必要

チームベロシティ比較は Standard プランの機能です。Free プランでは利用できません。

よくある設定ミスと対処法

プロジェクトがリストに表示されない

GitHub Projects V2 のみ対応しています。クラシック Projects は表示されません。また、Organization のプロジェクトには OAuth で read:project と read:org のスコープ許可が必要です。

ベロシティ比較でエラーが表示される

Iteration フィールドが未設定のプロジェクトではベロシティ比較が利用できません。GitHub Projects の Settings > Custom fields から Iteration フィールドを追加してください。

バーンダウンチャートが平坦なまま

Issue を Close しないとバーンダウンに反映されません。作業完了時は Issue を Close してください。ステータスを Done に変更するだけでは不十分です。

サイクルタイムが 0 と表示される

ステータスの変更履歴がない場合、サイクルタイムを計算できません。アイテムを追加した後、ステータスを順に変更してください。

メンバー別ベロシティが「unassigned」に集中する

Issue や PR に Assignee が設定されていない可能性があります。担当者を割り当てることで、メンバー別の集計が正しく表示されます。