【入門編】CircleCI APIを活用したCI/CDの可視化：ダッシュボードを自作してエンジニアリング組織の生産性を数値化する – バージョン管理・CI/CD活用バイブル

こんにちは！日々の開発、本当にお疲れ様です。
CI/CDツールとしてCircleCIを導入し、コードをプッシュするたびに自動でテストが走る環境が整うと、それだけでなんだか誇らしい気持ちになりますよね。「よし、モダンな開発ができているぞ！」と。

でも、しばらく運用していると、こんなモヤモヤを感じたことはありませんか？

  • 「最近、なんだかビルドが遅い気がするけど、気のせい？」
  • 「どのテストが一番ボトルネックになっているのか、感覚でしか分からない」
  • 「チームのデリバリー速度が上がっているのか、数字で証明できない」

そう、多くのチームが「CI/CDを導入した」という満足感で止まってしまい、「CI/CDのデータを資産として活用する」という次のステージに進めていません。

今回は、CircleCI API v2を駆使して、ビルドの成功率や実行時間を自動で収集し、ダッシュボードとして可視化する方法を解説します。これをマスターすれば、あなたのチームのボトルネックが丸裸になり、データに基づいた劇的な生産性向上が実現できますよ。

それでは、一緒に一歩ずつ進んでいきましょう！

—

1. CircleCI APIの役割と、今回やることの全体像

そもそも、CircleCIのダッシュボード（Web画面）があるのに、なぜわざわざAPIを叩いて自作するのでしょうか？

標準のUIは「今のビルドが成功しているか」「過去数回の履歴はどうか」を見るには十分ですが、「過去3ヶ月間の平均ビルド時間の推移」や「曜日ごとのキュー待ち時間の傾向」といった、組織の健康状態をマクロに分析するには少し物足りません。

そこで登場するのが CircleCI API v2 です。これを使うと、CircleCIが裏側で持っているすべての実行ログやメトリクスを、JSON形式で自由にごっそり取得できるようになります。

今回構築するアーキテクチャ

1. データ収集: 定期実行スクリプト（PythonやNode.jsなど）からCircleCI API v2を叩く
2. 蓄積・可視化: 取得したデータをGoogleスプレッドシート（またはGrafana）に流し込む
3. 分析: チームの「平均待ち時間」「成功率」「ボトルネックジョブ」を可視化する

「APIを叩く」と聞くと難しそうに聞こえるかもしれませんが、要はWebブラウザの代わりにプログラムからCircleCIに「最近のビルド結果を教えて！」と聞きに行くだけです。安心してくださいね。

—

2. 基礎セットアップ：APIトークンの発行と接続確認

まずは、CircleCI APIとおしゃべりするための「通行証（パーソナルアクセストークン）」を発行しましょう。

Step 1: パーソナルアクセストークンの発行

1. CircleCIのWeb画面にログインします。
2. 画面左側のメニューから 「User Settings（ユーザー設定）」 を開きます。
3. 「Personal API Tokens」 を選択し、「Create New Token」をクリックします。
4. トークンの名前（例: `dashboard-metrics-collector`）を入力し、発行します。
5. 発行されたトークンは一度しか表示されないため、必ず安全な場所にメモしておいてください！

Step 2: 動作確認（Hello World!ならぬ、Hello CircleCI API）

お手元のターミナルを開いて、以下のコマンドを叩いてみてください。`YOUR_TOKEN` の部分をご自身のトークンに、`your-org/your-repo` を対象のGitHub/Bitbucketのリポジトリ名に置き換えます。

curl -X GET \
–header “Circle-Token: YOUR_TOKEN” \
“https://circleci.com/api/v2/project/gh/your-org/your-repo/pipeline”

どうでしょう？ ズラッとJSON形式のデータが返ってきましたか？
おめでとうございます！これでCircleCI APIへの扉が開きました。この返ってきたデータの中に、私たちが欲しかった「お宝（メトリクス）」が眠っています。

—

3. 実践：APIからデータを抽出し、スプレッドシートに蓄積する

ここからは、実際にデータを収集するスクリプトを書いていきます。今回は、最も手軽で誰でも始めやすい Googleスプレッドシート ＋ Google Apps Script (GAS) を使った方法をご紹介します。（もちろん、Pythonで書いてGrafanaに送ることも基本の考え方は同じです）

Google Apps Scriptでの実装例

Googleスプレッドシートを開き、メニューの 「拡張機能」>「Apps Script」 を選択して、以下のコードを貼り付けてみてください。

// CircleCI APIから直近のパイプライン情報を取得してスプレッドシートに書き出すスクリプト

function fetchCircleCI(); {
const token = ‘YOUR_CIRCLECI_API_TOKEN’; // 先ほど発行したトークン
const org = ‘your-org’; // 組織名（GitHubのユーザー名や組織名）
const repo = ‘your-repo’; // リポジトリ名

// CircleCI API v2のパイプラインエンドポイント
const url = `https://circleci.com/api/v2/project/gh/${org}/${repo}/pipeline?circle-token=${token}`;

const options = {
‘method’: ‘get’,
‘contentType’: ‘application/json’,
‘muteHttpExceptions’: true
};

try {
const response = UrlFetchApp.fetch(url, options);
const data = JSON.parse(response.getContentText());

// スプレッドシートの準備
const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

// ヘッダー行がなければ作成
if (sheet.getLastRow() === 0) {
sheet.appendRow([‘Pipeline ID’, ‘Created At’, ‘Status’, ‘Trigger Actor’]);
}

// 取得したパイプライン情報をループしてシートに追記
// （実際には重複チェックなどを入れるとより実用的になります）
data.items.forEach(item => {
sheet.appendRow([
item.id,
item.created_at,
item.state, // 注意: パイプライン自体のstateはrunning/completedなど。ジョブの成否はワークフロー詳細から取得します
item.trigger.actor.login
]);
});

Logger.log(‘データの取得と書き出しが成功しました！’);

} catch (error) {
Logger.log(‘エラーが発生しました: ‘ + error.toString());
}
}

このスクリプトを毎日1回（トリガー機能を使用）自動実行するように設定しておくだけで、あなたの手元にCircleCIの生データがコツコツと溜まっていきます。

—

4. 単なるビルド管理から、メトリクス分析への進化

データを集め始めたら、いよいよエンジニアリング組織の生産性を可視化するフェーズです。ダッシュボードで見るべき「3大重要メトリクス」をご紹介します。

① ビルド成功率 (Build Success Rate)

  • 見ているもの: 全ビルドのうち、何パーセントが成功しているか。
  • 分析のヒント: この数値が急激に下がっている場合、テストの不安定さ（Flaky Tests）が増しているか、mainブランチへのマージ規律が緩んでいないかのサインです。目標値は常に90%以上をキープしたいところです。

② 平均キュー待ち時間 (Queue Time)

  • 見ているもの: 「ビルドしたい」とリクエストしてから、実際にリソース（ランナー）が割り当てられて実行が始まるまでの時間。
  • 分析のヒント: ここが長い場合、CircleCIの並列実行数（Concurrency）の制限に引っかかっているか、不要に多くのジョブを並列化しすぎてリソースが枯渇しています。開発者の「待ち時間」という名の生産性泥棒をここで特定できます。

③ 各ジョブの実行時間 (Job Duration)

  • 見ているもの: テストスイートやビルドなど、個別のジョブにかかっている時間。
  • 分析のヒント: 「どのテストが全体の足を引っ張っているのか？」を一目で分かるようにします。例えば、E2Eテストが15分かかっているなら、それを並列化（Parallelism）したり、ユニットテストと切り離して夜間実行にするなどのネクストアクションが打てるようになります。

—

まとめ：データを味方につけて、心地よい開発チームへ

今回は、CircleCI API v2を活用したCI/CDの可視化について解説しました。

  • CircleCI API v2 を使えば、リッチなビルドデータをプログラムから自由に取得できる。
  • スプレッドシートやGASなどの身近なツールと組み合わせるだけで、立派なメトリクス収集基盤が作れる。
  • 成功率、待ち時間、実行時間を可視化することで、チームの真のボトルネックが浮き彫りになる。

「なんとなく遅い気がする」という感覚的な議論から、「このテストの実行時間が過去2週間で12%伸びているから、リファクタリングしよう」というデータに基づいたエンジニアリング文化へ。

これをマスターすれば、あなたのチームのデリバリースピードは見違えるほどスムーズになり、毎日の開発作業がもっと楽しく、もっと楽になりますよ。ぜひ、今日の業務の合間にAPIを叩いてみてくださいね！

スポンサーリンク
タイトルとURLをコピーしました