アプリケーション開発におけるCICDパイプラインの導入には、ダッシュボードの設定またはパイプラインを定義したYAMLファイルの作成が必要です。
CircleCIでは最新版のCLIを利用することで、これらのセットアップ作業をコマンドベースで完結させることができます。
この記事では、CircleCI CLI (Version 1系列)を利用して、プロジェクトのセットアップからConfigのYAMLファイル生成、そしてパイプライン実行と失敗ログの取得までの手順を紹介します。
事前準備
この記事の作業を実行するには、CircleCI CLIが必要です。
Homebrewをお使いの場合は、以下のコマンドでインストールできます。
brew install circleci
WindowsやLinux系でのインストール方法などは、CircleCI CLIのWEBサイトTOPページをご確認ください。
本記事の検証に使用したCLIのバージョンは以下です。
% circleci version
circleci 1.0.46087-pre (0560a043ef86)
プロジェクトとリポジトリを作る
まずCircleCIでのCIをセットアップするプロジェクトを作りましょう。今回はHonoのscaffoldを使ってNode.jsプロジェクトを作りました。
% npm create hono
create-hono version 0.19.4
✔ Target directory hono-cci-cli-setup
✔ Which template do you want to use? nodejs
✔ Do you want to install project dependencies? Yes
✔ Which package manager do you want to use? pnpm
✔ Cloning the template
✔ Installing project dependencies
🎉 Copied project files
テストを Claude Code でセットアップする
このテンプレートにはtestスクリプトが含まれていません。今回はClaude Codeを利用して、 Vitestの追加とsrc/app.test.tsとvitest.config.tsを作った状態で進めました。
Git と GitHub をセットアップする
続いてGitHubリポジトリを用意しましょう。npm create honoはgitの初期化を行わないため、git initを先に実行します。
% git init
Initialized empty Git repository in /Users/hidetaka/sandboxes/hono-cci-cli-setup/.git/
リポジトリができたら、生成されたファイルをコミットします。
% git add .
% git commit -m init
[main (root-commit) 5c8cf00] init
6 files changed, 639 insertions(+)
その後ghコマンドでリポジトリをセットアップしましょう。
% gh repo create hono-cci-cli-setup --source=. --public
✓ Created repository hidetaka-cci/hono-cci-cli-setup on github.com
https://github.com/hidetaka-cci/hono-cci-cli-setup
✓ Added remote git@github.com:hidetaka-cci/hono-cci-cli-setup.git
これで、circleci onboardがスキャンできる状態になりました。
circleci onboard で 対話形式に CI とワークフローをセットアップする
circleci onboardは、リポジトリのスキャンからCircleCI側のプロジェクト作成までを対話形式で進めるコマンドです。引数なしで実行すると、最初に何をするかを選択します。
% circleci onboard
? What would you like to do?
› Scan this repo and generate config
Sign up for CircleCI
Configファイルを生成する
Scan this repo and generate configを選ぶと、実行される内容が先に提示されます。リポジトリの言語スタックとテストの検出、テストのローカル実行、.circleci/config.ymlの生成、CircleCIへのサインアップの4つです。
configの生成だけを実行する、circleci config generateコマンドも用意されています。
circleci onboard will:
• Scan your repo for the language stack and tests
• Run your tests locally
• Generate a starter .circleci/config.yml
• Sign you up for CircleCI
This will run in: /Users/hidetaka/sandboxes/hono-cci-cli-setup
Press Enter to continue · Esc to cancel
[Enter]キーを入力すると、生成するconfigに設定予定のテストコマンドを実際に実行します。
✓ Detected typescript project (cimg/node:26.7.0)
system: curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash - && sudo apt-get install -y nodejs --no-install-recommends && sudo rm -rf /var/lib/apt/lists/* && sudo npm install -g pnpm
install: pnpm install
test: pnpm test
Running tests ...
✓ src/app.test.ts (1 test) 9ms
Test Files 1 passed (1)
Tests 1 passed (1)
✓ Tests passed
✓ Generated /Users/hidetaka/sandboxes/hono-cci-cli-setup/.circleci/config.yml
✓ Already signed in as hidetaka-cci
実行後、circleci/config.ymlファイルが作成されます。このようにconfig.ymlの書き方を知らない状態でも、コマンド１つでテストをCircleCI上で実行できるようになります。
自動生成されたCI YAMLファイルをさらに改善するには、CircleCIが公開しているAgent Skillが使えます。
設定方法やレビュー方法などは、以下の記事をご覧ください。
CircleCI 公式スキルで、 CI の設定を AI に診断させる — ボトルネック・コスト削減診断から修正 PR まで
CircleCI プロジェクトを作成する
configを書き出したあと、onboardはサインイン済みのアカウントでCircleCI側のプロジェクト作成に進みます。ここでの対話入力は2回で、1回目が組織の選択、2回目がプロジェクト名の入力です。
1回目の組織の選択では、アカウントが所属している組織が一覧で表示されます。上下キーでカーソルを動かし、Enterで確定してください。選んだ組織の配下にプロジェクトが作られます。
Let's create your CircleCI project.
? Which organization should this project belong to?
gh/hideokamoto (hideokamoto)
gh/hidetaka-cci (hidetaka-cci)
↑/↓ move · enter select · esc quit
2回目はプロジェクト名の入力です。リポジトリ名が入力欄に表示されているため、変更しないならそのままEnterで確定します。
Project name
> hono-cci-cli-setup
enter confirm · esc cancel
ここで確定した名前が、CircleCI上でのプロジェクト名になります。この2つの入力でonboardは終わり、プロジェクト作成までが1コマンドに含まれているため、別のコマンドを追加で打つ必要はありません。
作成されたプロジェクトはcircleci project getで確認できます。プロジェクトID、スラッグ、デフォルトブランチが返ります。
% circleci project get
• Name: hono-cci-cli-setup
• Slug: gh/hidetaka-cci/hono-cci-cli-setup
• Project ID: ddb1db8c-ee58-4504-b28c-5204858b1030
• Organization: hidetaka-cci
• Provider: GitHub
• Default Branch: main
変更した YAMLファイルをコミットする
ここまででCircleCI側の準備は終了です。ただ、circleci onboardコマンドはconfigを生成するだけでコミットしません。CircleCIはpushされたconfigを読んでパイプラインを実行するため、コミットとpushは自分で行う必要があります。
% git add .circleci/
% git commit -m 'init ci'
% git push origin main
これでCircleCI上で、最初のパイプラインが実行されます。
push した run を CLI で追う
push後はcircleci run watchでパイプラインの実行状況を追跡できます。CircleCIでは、トリガーが発火するたびに作られる1回の実行をrunと呼びます。引数なしで実行すると、現在のブランチの最新runを対象に、完了するまで待機します。
% circleci run watch
Watching run 82d26617-4bc3-4c94-8904-32fd7d022f93 (main)
build ✗ failed 23s
build ✗ failed build
✗ Run 82d26617-4bc3-4c94-8904-32fd7d022f93 failed (34s)
error: Run 82d26617-4bc3-4c94-8904-32fd7d022f93 failed.
Suggestions:
• View logs for failed job "build": circleci job get <job-id>
CIの実行結果を監視するワークフローを作る場合、git push && circleci run watchのような書き方にすることで、結果を監視して次のステップに進めるようにできます。
失敗の原因を特定する 2つのコマンド
CLIには、失敗したステップの出力だけを取り出す手段が2つあります。
circleci run get --failure-report: エラー結果をようやくして表示
1つ目はcircleci run get --failure-reportです。失敗したすべてのステップの出力を要約して一度に表示します。job IDを調べる前でも使えるため、runが落ちた直後の最初の一手になります。
% circleci run get --failure-report
## workflow: build
### job: build
#### step 103: install [exit: 1]
? Verifying lockfile against supply-chain policies (130 entries)...
✗ Lockfile failed supply-chain policy check (130 entries in 1.3s)
[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 9 lockfile entries failed verification:
@biomejs/biome@2.5.9 was published at 2026-08-17T23:01:11.000Z, within the minimumReleaseAge cutoff (2026-08-17T05:31:38.508Z)
circleci job output get: 失敗したジョブのログを取得する
2つ目はcircleci job output getです。ステップ番号を指定して、そのステップの生の標準出力と標準エラーを取得します。要約では足りない場合や、失敗の前後の出力を含めて読みたい場合に使います。
% circleci job output get 0c8a14b6-8f1d-46fe-ab76-50d08716595e --step-num 103
? Verifying lockfile against supply-chain policies (130 entries)...
Progress: resolved 55, reused 0, downloaded 54, added 54
✗ Lockfile failed supply-chain policy check (130 entries in 1.3s)
[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 9 lockfile entries failed verification:
...
Exited with code exit status 1
--condensedを付けると、エラーに関係する行だけがサーバー側で絞り込まれて返ります。リファレンスではexperimentalとされているフラグですが、原因が1行で済む失敗では最も速く読めます。次は別のrunでsystemステップが落ちたときの出力です。
% circleci job output get 34894851-604b-4772-ba22-9079281f4466 --step-num 102 --condensed
sudo: corepack: command not found
今回の失敗はパッケージマネージャーがlockfileを検査して拒否したもので、対処は依存構成によって変わります。ここでは原因の特定までとし、修正は後半で扱います。
circleci run getとcircleci job getでパイプラインを深掘り調査
このほかにも、CIの実行速度やボトルネックの調査など、さまざまな形でパイプラインのrunを分析するケースが運用では出てきます。runの中身を見るにはcircleci run getを使います。runはworkflowを含み、workflowはjobを含むという構造になっているため、この1コマンドで失敗したjobのIDまで辿れます。
% circleci run get 82d26617-4bc3-4c94-8904-32fd7d022f93
• Branch: main
• Commit: 870b0a0
• Subject: init ci
• Status: failed
### build
• Status: ❌ failed
• Duration: 23s
Name │ Status │ Type │ ID
───────┼───────────┼───────┼──────────────────────────────────────
build │ ❌ failed │ build │ 0c8a14b6-8f1d-46fe-ab76-50d08716595e
job IDが分かったので、circleci job getでステップ単位の内訳を確認します。どのステップで落ちたかは、この時点で確定します。なおrun getが返した23sはworkflowの所要時間であり、jobの所要時間はこちらで別に返ってきました。
% circleci job get 0c8a14b6-8f1d-46fe-ab76-50d08716595e
• Status: ❌ failed
• Duration: 21.1s
# │ Name │ Status │ Duration │ Exit Code
─────┼─────────────────────────────────┼──────────────┼──────────┼───────────
0 │ Spin up environment │ ✅ succeeded │ 5.5s │ -
99 │ Preparing environment variables │ ✅ succeeded │ 12ms │ -
101 │ Checkout code │ ✅ succeeded │ 1.1s │ -
102 │ system │ ✅ succeeded │ 11.7s │ 0
103 │ install │ ❌ failed │ 2.1s │ 1
ステップ103のinstallが終了コード1で失敗しています。イメージの起動、チェックアウト、systemステップは通っているため、原因は依存インストールの段にあると絞り込めました。
まとめ
CircleCIのセットアップは、circleci onboardでリポジトリのスキャンからconfig生成、プロジェクト作成までを1コマンドで進められます。生成前にテストコマンドが手元で通ることを確認するため、書き出されるconfigは走らせる対象が確定した状態から始まります。あとはpushしてcircleci run watchで結果を待つだけです。失敗したらcircleci run get --failure-reportとcircleci job output get --step-numで、ステップ単位のログまで辿れました。CircleCIのアカウントを作った直後の状態から、最初のパイプラインを実行して失敗したステップのログに到達するまで、ブラウザを開く必要はありません。
同じCLIはMCPサーバーとしても動作するため、AIエージェント側からCircleCIのデータやconfig検証を扱う構成も作れます。設定方法は「Cursor で CircleCI の Agent Skill と MCP サーバーを連携させ、CI設定ファイルの検証を自動化する」で紹介しています。各コマンドのフラグと出力仕様はCircleCI CLI Referenceを参照してください。