【Googleスプレッドシート】CircleCIのビルドステータスをSheetsに取得!CI状況の集約

複数のCircleCIプロジェクトを運用していると、ビルドの成否を一覧で確認したい場面がよくあります。各プロジェクトのダッシュボードを開くのは手間ですし、チーム全体で状況を共有するにはスプレッドシートにまとめるのが便利です。この記事では、Google Apps Scriptを使ってCircleCI APIからビルドステータスを取得し、Googleスプレッドシートに自動で書き込む方法を解説します。手順に沿えば、CI状況の一元管理が可能になります。

CircleCIのビルドステータスをスプレッドシートに集約するメリット

CircleCIはパイプラインの可視化に優れていますが、複数プロジェクトを横断して見たい場合や、非エンジニアのメンバーに状況を共有するにはスプレッドシートが適しています。Google Apps Scriptを使えば、手動でスクレイピングする手間を省き、リアルタイムに近い形でステータスを一覧化できます。特に、APIのレスポンスはJSON形式で簡単に扱えるため、特定のブランチの最新ビルドやジョブの成否を効率的に取得できます。

CircleCI APIからビルドステータスを取得する手順

ここでは、実際にApps Scriptを書いてスプレッドシートにデータを反映するまでの流れを説明します。事前にCircleCIのアカウントと対象プロジェクトがあることを確認してください。

ステップ1: CircleCIのパーソナルAPIトークンを生成する

1. CircleCIの設定画面を開く
   CircleCIにログインし、画面右上のユーザーアイコンから「User Settings」を選択します。
2. API Tokensタブをクリックする
   左側のメニューから「API Tokens」を選び、「Create New Token」ボタンを押します。
3. トークン名を入力して生成する
   任意の名前(例:spreadsheet-integration)を入力し、「Add API Token」をクリックします。表示されたトークンをコピーして安全な場所に保存します。

ステップ2: スプレッドシートを準備し、Apps Scriptエディタを開く

1. 新しいスプレッドシートを作成する
   Googleスプレッドシートを開き、新しいシートを作成します。シート名は「BuildStatus」などに変更するとわかりやすいです。
2. 拡張機能メニューからApps Scriptを開く
   メニューバーの「拡張機能」→「Apps Script」をクリックします。新しいタブでスクリプトエディタが開きます。

ステップ3: APIリクエストを送る関数を作成する

1. スクリプトエディタにコードを記述する
   以下の関数を記述します。この関数では、指定したプロジェクトの最新ビルド情報を取得し、ステータスやブランチ名を返します。
   function getLatestBuild(projectSlug, branch) {
var token = 'YOUR_CIRCLECI_TOKEN';
var url = 'https://circleci.com/api/v2/project/' + projectSlug + '/pipeline?branch=' + encodeURIComponent(branch);
var options = {
'headers': {
'Circle-Token': token
},
'muteHttpExceptions': true
};
var response = UrlFetchApp.fetch(url, options);
var json = JSON.parse(response.getContentText());
return json.items[0] || null;
}
2. プロジェクトスラッグを確認する
   CircleCIのプロジェクトページのURLからスラッグを確認します。形式は「gh/ユーザー名/リポジトリ名」です。

ステップ4: ビルドステータスをシートに書き出すメイン関数を作成する

1. シートにヘッダーを設定する
   以下の関数で、シートの1行目に「プロジェクト」「ブランチ」「ステータス」「ビルド番号」「更新日時」のヘッダーを書き込みます。
   function setHeaders() {
var sheet = SpreadsheetApp.getActiveSheet();
var headers = ['プロジェクト', 'ブランチ', 'ステータス', 'ビルド番号', '更新日時'];
sheet.getRange(1, 1, 1, headers.length).setValues([headers]);
}
2. データを取得して書き込む関数を作成する
   以下の関数では、複数のプロジェクトをループして各最新ビルドのステータスをシートに追記します。
   function updateBuildStatus() {
var sheet = SpreadsheetApp.getActiveSheet();
var data = [
{slug: 'gh/your-org/repo1', branch: 'main'},
{slug: 'gh/your-org/repo2', branch: 'develop'}
];
var output = [];
data.forEach(function(proj) {
var build = getLatestBuild(proj.slug, proj.branch);
if (build) {
var status = build.state;
var buildNum = build.number;
var updated = new Date(build.updated_at);
output.push([proj.slug, proj.branch, status, buildNum, updated]);
} else {
output.push([proj.slug, proj.branch, 'No builds', '', '']);
}
});
// 既存のデータをクリアして新しい行を書き込む(2行目以降)
var lastRow = sheet.getLastRow();
if (lastRow > 1) sheet.getRange(2, 1, lastRow-1, 5).clearContent();
if (output.length > 0) sheet.getRange(2, 1, output.length, 5).setValues(output);
}

ステップ5: 関数を実行して動作を確認する

1. setHeaders関数を実行する
   スクリプトエディタの関数一覧から「setHeaders」を選択し、実行ボタンを押します。初回は権限の承認が必要です。承認後、シートにヘッダーが書き込まれます。
2. updateBuildStatus関数を実行する
   同様に「updateBuildStatus」を実行します。シートの2行目以降に各プロジェクトの最新ビルド情報が表示されれば成功です。

ステップ6: トリガーを設定して自動更新する

1. Apps Scriptのトリガーメニューを開く
   スクリプトエディタの左側にある時計アイコン「トリガー」をクリックします。
2. 新しいトリガーを追加する
   「トリガーを追加」をクリックし、実行する関数を「updateBuildStatus」、イベントのソースを「時間主導型」、時間の間隔を「10分おき」などに設定します。これで定期的にビルドステータスが更新されます。

API連携で注意すべきポイント

APIトークンの管理

APIトークンは他人に知られると悪用される可能性があります。スクリプト内に直接記述するのは避け、スクリプトプロパティに保存することを推奨します。スクリプトエディタの「プロジェクトの設定」→「スクリプトプロパティ」に「CIRCLECI_TOKEN」というキーでトークンを保存し、コード内ではPropertiesService.getScriptProperties().getProperty('CIRCLECI_TOKEN')で取得します。

レート制限への対処

CircleCI APIにはレート制限があり、短時間に多数のリクエストを送ると429エラーが返ることがあります。複数プロジェクトを取得する場合は、Utilities.sleep()でリクエスト間に1秒以上の間隔を入れると安全です。また、一度に取得するプロジェクト数が多い場合は、トリガーの間隔を長めに設定してください。

エラーハンドリングの実装

ネットワーク障害やAPIの一時的な問題に備えて、try...catchでエラーを捕捉し、エラー内容をシートの別セルに記録するなどの処理を追加すると運用が楽になります。

手動更新と自動更新の比較

まとめ

この記事では、Google Apps ScriptとCircleCI APIを組み合わせてビルドステータスをスプレッドシートに自動取得する方法を紹介しました。APIトークンの発行からスクリプトの作成、トリガー設定までの流れを実践すれば、手間なくCI状況を一元管理できます。次は、取得したステータスを条件付き書式で色分けしたり、Slack通知と連携するなど、さらに便利な応用を試してみてください。