GitHub Copilot usage metrics APIをETLやBIダッシュボードへ取り込んでいる場合、今回の更新で最初に確認すべきなのは、追加フィールドを既存のJSONパーサーや固定スキーマが拒否しないかです。
結論として、今回の変更は既存フィールドの削除や型変更ではなく、AI活用フェーズ別の集計に2つのレビュー指標を追加するものです。通常のJSONクライアントであれば緊急の移行は不要ですが、厳格なJSON Schema、固定列のETL、レスポンス全体を比較するスナップショットテストでは修正が必要になる可能性があります。GitHubではレスポンスフィールドの追加を非破壊的な変更として扱っています。(The GitHub Blog)
なお、対象として指定された2026年7月8日の更新に対応する公式Changelogは、ページ上では2026年7月7日付です。社内の変更管理台帳では、確認日と公式発表日を分けて記録すると混乱を防げます。(The GitHub Blog)
GitHub Copilot usage metrics APIの更新で何が変わったのか
今回の更新では、企業または組織の利用状況レポートに含まれるtotals_by_ai_adoption_phaseへ、次の2フィールドが追加されました。
| 追加フィールド | 公式定義 | 集計対象 |
|---|---|---|
avg_pull_requests_minutes_to_review | Pull Request作成から最初のレビューまでの時間を分単位で示す指標 | マージされたPull Request |
avg_pull_requests_review_cycles | マージまでに受けたレビュー提出回数を示す指標 | マージされたPull Request |
公式Changelogでは、いずれも中央値を用いた指標として説明されています。対象となるのは最終的にマージされたPull Requestだけで、レビュー済みでもマージされなかったPull Requestは集計に入りません。また、Pull Requestはマージされた日に一度だけ計上されます。(The GitHub Blog)
「time-to-adoption」を測る更新ではない
更新名の「Add review cycles and time to adoption phases in the usage API」は、Copilotの導入完了までにかかった時間を測定する機能と誤読しやすい表現です。
実際に追加された時間指標は、Pull Request作成から最初のレビューまでの時間です。これをCopilotのAI活用フェーズ別に比較できるようになった、という更新です。
つまり、今回のAPIで直接分かるのは次の内容です。
- Copilotの活用段階が異なるグループ間で、レビュー開始までの時間に差があるか
- マージまでに何回のレビュー提出が発生しているか
- コードレビュー工程の待ち時間や手戻りがどこにあるか
一方、Copilotライセンス付与から初回利用までの日数や、利用者が上位の活用フェーズへ移行するまでの期間は、今回追加されたフィールドだけでは測定できません。
AI活用フェーズは既存の分類をそのまま利用する
totals_by_ai_adoption_phaseは、直近28日間のCopilot利用状況に応じてユーザーを分類する既存の集計です。今回の更新によって、フェーズの定義やユーザーの分類方法は変更されていません。
| フェーズ | 概要 |
|---|---|
| Phase 0 | 対象となるCopilot利用が確認されないユーザー |
| Phase 1 | コード補完やIDE内のエージェントモードを中心に利用 |
| Phase 2 | Copilot coding agent、コードレビュー、CLIなど、単一のエージェント領域を利用 |
| Phase 3 | 複数のエージェント領域または新しいGitHub Copilotアプリを利用 |
フェーズ判定はローリング28日間の利用状況に基づきます。そのため、同じユーザーでも利用状況の変化によって所属フェーズが変わる可能性があります。今回の2指標は、この既存フェーズごとのレビュー状況を把握するために追加されたものです。(The GitHub Blog)
APIレスポンスの仕様差分
変更点と、今回変更されていない部分を整理すると次のようになります。
| 確認項目 | 更新後の扱い |
|---|---|
| 追加場所 | totals_by_ai_adoption_phase内 |
| 新しい指標 | 初回レビューまでの時間、レビュー提出回数 |
| 対象レポート | Enterprise／Organizationの1日レポートと28日レポート |
| 集計対象 | マージされたPull Requestのみ |
| 計上日 | Pull Requestがマージされた日 |
| 同一PRの計上回数 | 1回 |
| フェーズ定義 | 変更なし |
| エンドポイント | 変更なし |
| 認証方式 | 変更なし |
| 既存フィールド | 削除・名称変更の案内なし |
次は説明用に簡略化したレスポンス例です。数値は実データではありません。
{
"phase": "Phase 2",
"phase_number": 2,
"total_engaged_users": 120,
"avg_pull_requests_median_minutes_to_merge": 480,
"avg_pull_requests_minutes_to_review": 95,
"avg_pull_requests_review_cycles": 2
}既存のフェーズ別オブジェクトを維持したまま、末尾に2つのキーが追加されるイメージです。フィールドの順序はJSONの意味を持たないため、キーの並び順を前提にした処理は避ける必要があります。
また、フィールド名はavg_で始まりますが、公式Changelogの説明では中央値として定義されています。社内ダッシュボードで単に「平均レビュー時間」と表示すると誤解を招くため、「初回レビューまでの時間（公式定義に基づく集計値）」など、意味が分かるラベルを付けるのが安全です。(The GitHub Blog)
既存実装との互換性
GitHubのREST APIでは、既存レスポンスへのフィールド追加は非破壊的な変更に分類されます。破壊的変更は新しいAPIバージョンで提供されますが、フィールド追加だけを理由に新しいバージョンへ切り替える必要はありません。(GitHub Docs)
ただし、実際に影響がないかどうかは、受信側の実装によって変わります。
| 既存実装 | 想定される影響 | 必要な対応 |
|---|---|---|
| 未知のJSONフィールドを無視する | 原則として影響なし | 通常の回帰テストのみ |
JSON SchemaでadditionalProperties: falseを指定 | 検証エラーになる可能性 | 新フィールドをスキーマへ追加 |
| DTOの厳格なデシリアライズ | 未知フィールドで失敗する可能性 | 未知フィールドを許容する設定へ変更 |
| レスポンス全体のスナップショット比較 | 差分テストが失敗 | 新フィールドを期待値へ追加 |
| 列固定のCSV・データウェアハウス取り込み | 列不足やマッピングエラーの可能性 | nullable列を追加して再テスト |
| 許可リスト方式で必要項目だけ抽出 | 既存処理は継続するが新指標を取得できない | 活用する場合のみ抽出項目へ追加 |
| JSONキー数や並び順に依存 | 誤動作する可能性 | キー名による参照へ修正 |
特に注意したいのが、自動生成した型付きクライアントです。多くのライブラリは未知のフィールドを無視しますが、設定や言語によっては例外を発生させます。
本番コードを変更する前に、次のような未知フィールドを追加したモックレスポンスを既存パーサーへ入力し、正常に処理できるか確認してください。
{
"existing_field": 100,
"avg_pull_requests_minutes_to_review": 95,
"avg_pull_requests_review_cycles": 2,
"future_unknown_field": "test"
}future_unknown_fieldを含めても正常に処理できれば、今後の追加フィールドにも耐えやすい実装になっています。
利用条件とレポートの取得方法
利用前に確認する条件
GitHub Copilot usage metrics APIを利用するには、対象の契約、ポリシー、権限を確認する必要があります。
| 項目 | 確認内容 |
|---|---|
| 契約 | GitHub Copilot BusinessまたはGitHub Copilot Enterprise |
| Enterpriseポリシー | Copilot usage metricsを利用可能な状態にする |
| Enterpriseレポートの権限 | Enterprise owner、billing manager、または許可されたカスタムロール |
| Organizationレポートの権限 | Organization owner、または許可されたユーザー |
| トークン | エンドポイントに対応したEnterpriseまたはOrganizationの読み取り権限 |
| APIバージョン | X-GitHub-Api-Versionヘッダーの明示を推奨 |
| データ反映 | 対象日終了後、少なくとも2日分のUTC日付が経過してから確認 |
REST APIのドキュメントでは、EnterpriseでCopilot usage metricsポリシーが有効になっていることが前提とされています。Enterprise用とOrganization用では、必要なロールやトークンスコープが異なるため、HTTP 403が返る場合はライセンスより先に権限を確認してください。(GitHub Docs)
また、利用データはリアルタイムではありません。対象日が終了してから2つの完全なUTC日が経過するまで反映されない場合があります。更新直後のテストでフィールドが見つからなくても、すぐに仕様未反映と判断しないことが重要です。(GitHub Docs)
Organizationの1日レポートを取得する例
次の例では、Organizationの2026年7月10日分のレポート情報を取得します。
ORG="your-organization"
DAY="2026-07-10"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer ${GITHUB_TOKEN}" \
-H "X-GitHub-Api-Version: 2026-03-10" \
"https://api.github.com/orgs/${ORG}/copilot/metrics/reports/organization-1-day?day=${DAY}" \
-o report-metadata.jsonこのAPIの初回レスポンスには、集計データそのものではなく、レポートファイルを取得するための署名付きダウンロードURLが含まれます。URLには有効期限があるため、取得後は速やかにファイルを保存します。(GitHub Docs)
DOWNLOAD_URL=$(jq -r '.download_links[0]' report-metadata.json)
curl -L "${DOWNLOAD_URL}" -o copilot-usage-report.ndjson複数のdownload_linksが返される可能性を考慮し、本番処理では配列全体をループして取得してください。
28日レポートを取得する場合は、次のエンドポイントを利用します。
/orgs/{org}/copilot/metrics/reports/organization-28-day/latest
/enterprises/{enterprise}/copilot/metrics/reports/enterprise-28-day/latest新フィールドが含まれているか確認する
NDJSON内の階層を固定せず、対象フィールドを再帰的に検索する例です。
jq -c '
..
| objects
| select(
has("avg_pull_requests_minutes_to_review")
or has("avg_pull_requests_review_cycles")
)
| {
phase,
phase_number,
total_engaged_users,
avg_pull_requests_minutes_to_review,
avg_pull_requests_review_cycles
}
' copilot-usage-report.ndjson既存システムへ組み込む前に、まず保存した生のNDJSONでフィールドの位置、値の型、欠損時の表現を確認するのが確実です。
テスト時に見落としやすいポイント
マージされていないPull Requestは集計されない
最も起きやすいテストミスは、レビュー済みのPull Requestを用意しただけで数値が変わると考えることです。
新しい2指標の対象は、最終的にマージされたPull Requestです。レビューを受けてもオープンのまま、またはマージせずクローズしたPull Requestは集計に含まれません。(The GitHub Blog)
作成日やレビュー日ではなくマージ日に計上される
たとえば、次のPull Requestがあるとします。
- 7月10日：Pull Requestを作成
- 7月11日：最初のレビューを受領
- 7月14日：修正後にマージ
このPull Requestは、7月10日や7月11日ではなく、7月14日のレポートへ計上されます。ただし、初回レビューまでの時間は7月10日の作成時刻から7月11日の最初のレビュー時刻までを基に計算されます。(The GitHub Blog)
日別レポートを検証するときは、作成日ではなくマージ日を指定してください。
レビューコメント数とレビュー提出回数を混同しない
avg_pull_requests_review_cyclesの公式説明で使われているのは、レビューコメント数ではなくreview submissionsです。
1回のレビュー提出に複数のインラインコメントが含まれることもあります。コメント件数を手作業で数えてAPI値と比較しても一致しない可能性があるため、レビュー提出イベントを基準に検証してください。
空のフェーズを想定する
対象期間中にマージされたPull Requestがないフェーズでは、数値を計算できません。公開Changelogだけでは、その場合にフィールドが省略されるのか、nullになるのか、0になるのかが明記されていません。
受信側では、次の3パターンをすべて処理できるようにします。
const minutesToReview =
phase.avg_pull_requests_minutes_to_review ?? null;
if (minutesToReview === null) {
console.log("対象データなし");
}データなしを0分として扱うと、「レビューが即時に完了した」と誤解されます。欠損値と実測値の0は明確に分けてください。
1件追加しても中央値が変わるとは限らない
新しいテスト用Pull Requestを1件マージしても、既存データの件数や分布によっては集計値が変化しない場合があります。
テストでは値が増減したかだけでなく、次の点を確認します。
| テスト観点 | 確認内容 |
|---|---|
| スキーマ | 2つのフィールドが読み取れるか |
| 型 | 数値、null、欠損を安全に処理できるか |
| 日付 | マージ日のレポートへ計上されるか |
| 除外条件 | 未マージのPull Requestが入っていないか |
| 互換性 | 既存フィールドの取り込みが継続できるか |
| 期間 | 1日レポートと28日レポートの両方で取得できるか |
| 将来耐性 | 未知のフィールドが増えても失敗しないか |
1日レポートと28日レポートの使い分け
両方のレポートで新しい指標を利用できますが、用途は異なります。
| レポート | 向いている用途 | 注意点 |
|---|---|---|
| 1日レポート | 障害、繁忙日、施策実施日の確認 | マージ件数が少ない日は値が大きく変動しやすい |
| 28日レポート | 導入傾向、フェーズ別比較、月次レビュー | 利用者のフェーズ移動や構成変化を含む |
日々の増減だけで施策の成功を判断するのではなく、1日レポートで異常を見つけ、28日レポートで継続的な傾向を確認する使い方が適しています。
AI活用フェーズは直近28日間の利用状況によって決まるため、前月と今月でPhase 2の値が変わっていても、同じユーザー集団を比較しているとは限りません。定点観測では、total_engaged_usersやtotal_pull_requests_mergedも併せて保存し、母数の変化を確認してください。(The GitHub Blog)
新指標をコードレビュー改善へ活用する方法
新しい2指標は、既存のマージ所要時間と組み合わせることで、レビュー工程のどこに問題があるかを判断しやすくなります。
| 観測された傾向 | 考えられる状態 | 確認・改善する内容 |
|---|---|---|
| 初回レビューまでが長く、レビュー回数は少ない | レビュアー割り当てや着手待ちがボトルネック | CODEOWNERS、通知、当番制、レビューSLAを確認 |
| 初回レビューは速いが、レビュー回数が多い | 要件の曖昧さ、PRの大きさ、品質不足による手戻り | PR分割、テンプレート、事前テストを改善 |
| 両方とも小さいが、マージまでが長い | CI、承認待ち、リリース制限がボトルネック | Actionsの実行時間、必須チェック、承認ルールを確認 |
| 上位フェーズほどすべて改善している | Copilot活用と効率改善に相関がある可能性 | 複数期間で再確認し、チームやPR規模の差も分析 |
| 上位フェーズほどレビュー回数が多い | AI生成量の増加に対しレビュー負荷が増えている可能性 | 生成コードの品質、テスト、PRサイズを確認 |
たとえば、初回レビューまでの時間が短縮しても、レビュー回数とマージまでの時間が増えていれば、単にレビュー開始が早くなっただけで、開発サイクル全体は改善していない可能性があります。
反対に、レビュー回数だけを減らすことを目標にすると、必要な指摘まで抑制するおそれがあります。指標は評価目的ではなく、工程改善の仮説を立てるために使うのが適切です。
フェーズ間の差をCopilotの効果と断定しない
Phase 3の初回レビュー時間がPhase 1より短くても、Copilotだけが原因とは限りません。
フェーズ間では、次の条件が異なる可能性があります。
- 開発者の経験年数
- チームの人数
- Pull Requestの変更行数
- リポジトリの種類
- レビュアーの配置
- CIの所要時間
- 必須承認数
- 休日やタイムゾーン
GitHub Copilot usage metrics APIの値だけで因果関係を証明するのではなく、Pull Requestのサイズやリポジトリ、チームなどのデータと組み合わせて分析してください。
OrganizationとEnterpriseではユーザーの所属や集約方法も異なるため、両者の数値を単純に一致させる用途には向きません。複数Organizationに所属するユーザーの扱いを含め、比較対象の範囲をそろえる必要があります。(GitHub Docs)
対応要否を判断する基準
今回の更新への対応レベルは、現在の利用方法によって判断できます。
| 現在の利用状況 | 対応要否 | 推奨対応 |
|---|---|---|
| APIレスポンスをそのまま保存している | 緊急対応は不要 | 保存処理が未知フィールドを許容するか確認 |
| 必要なキーだけを抽出している | 既存処理への影響は小さい | 新指標を使う場合のみ抽出処理を追加 |
| 厳格なJSON Schemaを使用している | 対応が必要 | 新フィールドを任意項目として追加 |
| 固定列のデータ基盤へ投入している | 対応が必要 | nullable列、データ辞書、型定義を追加 |
| スナップショットテストを使用している | 対応が必要 | 期待値更新と将来フィールドへの耐性を追加 |
| 開発生産性ダッシュボードを運用している | 導入価値が高い | 初回レビュー、レビュー回数、マージ時間を併記 |
| User、Team、Repositoryレポートだけを利用している | レポート構成の見直しが必要 | EnterpriseまたはOrganizationの1日・28日レポートを確認 |
| 未マージPRのレビュー状況も分析したい | 今回の指標だけでは不足 | Pull Requestイベントを別途取得して補完 |
| Usage metricsポリシーを無効にしている | API利用前の設定が必要 | ポリシー、ロール、トークン権限を確認 |
実務で行うべき対応手順
まず、既存のAPI取り込み処理が未知フィールドを許容しているか確認します。厳格なスキーマや固定列を使っている場合は、2つのフィールドを任意項目として追加してください。
次に、更新日以降かつUTC基準の反映待ち時間を満たした1日レポートを取得し、生のNDJSONを保存します。未マージのPull Requestではなく、レビュー後にマージされたPull Requestを含む日を選ぶことが重要です。
その後、次の順序で検証します。
- APIリクエストとレポートダウンロードが成功する
- 新しい2フィールドを検出できる
- 欠損、
null、数値を安全に処理できる - 既存フィールドの取り込み結果が変わっていない
- 1日レポートと28日レポートの両方を処理できる
- ダッシュボードの表示名が公式定義と矛盾していない
- 今後フィールドが追加されても処理が失敗しない
通常の寛容なJSON処理であれば、大規模な改修は不要です。一方、厳格なデータ基盤では、フィールド追加そのものが障害原因になり得ます。まず互換性テストを行い、その後にレビュー待ち時間、レビュー回数、マージ時間を組み合わせた可視化へ進むのが、最も安全で実用的な対応です。
コメント