CloudbuildでCursor CLIヘッドレスモードを動かす方法
はじめに
この記事はCursor Meetup Fukuokaにて紹介したGoogle CloudのCI/CDサービスであるCloud Build上でCursor CLIをインストールし、ヘッドレスモードで実行する方法を解説します
この仕組みを活用することで、例えばCloud Buildでのデプロイが失敗した際に、その原因調査から対処法のレポート作成までをCursorエージェントに自動実行させるといったことが可能になります
Cursor Meetup Fukuokaのアーカイブはこちら
Cursor CLIとヘッドレスモード
Cursor CLIとは、その名の通りCursorのエージェントをターミナル上で使用できる公式機能です
このCursor CLIにはヘッドレスモードが存在し、これを利用することで既存のスクリプトやCI/CDパイプラインに直接エージェントを組み込めるようになります
APIキーの発行
Cursor CLIのヘッドレスモードを使用するためには、CursorのAPIキーが必要です
Cursorの公式サイトにログインし、「Integrations」タブの「User API Keys」からAPIキーを発行してください
発行したAPIキーは後ほどCloud Buildから参照できるよう、Secret Managerに保管しておいてください
Cloudbuildコード
以下がCloud Build上でCursor CLIを実行するためのcloudbuild.yamlのサンプルコードです
steps:
- name: gcr.io/cloud-builders/gcloud
args:
- '-c'
- >
set -euo pipefail
# 依存パッケージをインストール（curl が無いと失敗する）
apt-get update && apt-get install -y curl ca-certificates &&
update-ca-certificates || true
# Cursor CLIをインストール
curl https://cursor.com/install -fsS | bash
# Cursor Agent を実行（インストーラが ~/.local/bin にシンボリックリンクを作成）
"$${HOME}/.local/bin/cursor-agent" -p "
{{プロンプト}}
" --force --model "${_MODEL}" --output-format=text
entrypoint: bash
secretEnv:
- CURSOR_API_KEY
options:
logging: CLOUD_LOGGING_ONLY
availableSecrets:
secretManager:
- versionName: 'projects/${PROJECT_ID}/secrets/cursor-api-key/versions/latest'
env: CURSOR_API_KEY
この設定では、ステップ内でcurlコマンドを使ってCursor CLIをインストールし、その後cursor-agentコマンドをプロンプトと共に実行しています
活用例：デプロイ失敗の自動調査
この仕組みの具体的な活用例として、Cloud Runへのデプロイが失敗した原因を自動調査させるケースが挙げられます
例えば、サービスアカウントに必要なIAM権限が不足しているためにCloudRunのデプロイが失敗したとします。通常であれば、開発者はエラーログを確認し、IAMの権限設定を見直すなどの調査が必要です
しかしCloud BuildにCursor CLIを組み込み、
他のCloud Buildの失敗をトリガーに動くような仕組みを導入すると
Cursorエージェントがgcloudコマンドなどを自動で実行し、ログのフィルタリング、サービスアカウントの権限確認、そして原因の特定と解決策の提示までを行わせることができます
課題
非常に強力な活用が期待できる一方で、現状大きな課題が一つ......
GitHub ActionsやCloud Build上でCursor CLIのヘッドレスモードを実行すると、リクエストの開始から終了までほぼ確実に30分程度の時間がかかってしまいます
Cursorのフォーラムでも同様の課題を抱えているユーザーが複数いるようですが、原因はまだ不明です。この実行時間はCI/CDのコストや作業効率に直結するため、現状では本格的な運用は厳しい印象です
改善を期待したいところ
まとめ
現状、約30分の実行時間がかかってしまうという課題は残るものの、この技術には高いポテンシャルを感じます
Cursor Meetup Fukuokaでは公式ドキュメントにも載っているGitHubActionsを使用したドキュメント生成を少し改造し、プルリクからmainにマージされたものをトリガーにREADEME.mdを自動で更新し、プルリクを作らせる事例や
上記のCloudbuild上でCursorCLIを実行し、CloudRunのビルドの失敗の調査といった事例を紹介しましたが、他にも多くのタスクで利用できると思います
またこの方法はエディタ上でのAIの操作などと違い、プロンプトやルールファイル、細かい設定などはチームで必ず共通となる上、既存のCIシステムに導入するだけなので学習コスト等もあまり高くなく、AI活用に詳しくない開発者でも簡単に恩恵を受けることができます
よってAI導入において、できる限り早く効果を実感したい場合にも使えるのではないかと思いました
直近では他のAIツールもCIシステムへの導入のための動きが見え始めているので
今後も研究を進められればと思います
Discussion