🐕

CircleCI CLI のセットアップと config.ymlの検証をローカルで行う

2025/07/04に公開

CircleCIのデプロイパイプラインはconfig.ymlファイルにて制御されます。

こちらの修正を行った際には実際にパイプラインを実行してテストを行う必要がありますが、それだと都度都度デプロイが行われてしまい簡単にテストを行うことが難しいケースもありますし、時間がかかります。

CircleCIのCLIを使うことでローカルでconfig.ymlの検証が可能となるので、今日はこちらをやってみます。

CircleCI CLI

https://circleci.com/docs/local-cli/
こちらが公式ドキュメントです。
GitHubレポジトリはこちら。

CircleCI のさまざまな機能をターミナルから直接扱えるツールとなっていて、上記で触れた設定ファイルのローカル検証以外にも、動的な検証ファイルの構成（これは後日またブログで触れたいと考えています）、商用環境におけるパイプラインやワークフローの実行等の機能が備わっているようです。

さっそくやってみる

1. chocolately 環境の整備

Windows環境へのインストールはchocolatelyを使うようなのでまずはその環境を整えます。
https://chocolatey.org/
chocolatelyはシステムフォルダであるC:\ProgramData\へのインストールをデフォルトで行いますので、管理者権限でのインストールが必要です。このためVSCodeではなくPowerShellで実行します。

右クリックで管理者として実行を選択します。

その後以下のコマンドを実行すればインストールは完了です。

Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

インストールが完了したらVSCodeでchoco --versionを実行しバージョンが戻れば成功です。

2.初期セットアップ

引き続きPowerShellで以下を実行しCLI本体をインストールします。

choco install circleci-cli -y

ここからはVSCodeで作業を行っていきます。まずはCLI本体をインストールします。
次にマネージメントコンソールからAPIトークンを発行します。
画面右上のプロファイルをクリックしてUser Settings画面を開き、Personal API Tokensを選択します。

Create New Tokenをクリックして適当な名前を付ければ発行されますのでそれをメモしておきます。

次にcircleci setupコマンドを実行して、APIトークンと接続先のURLをCLIに保存します。

circleci setup

CircleCI API Token ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●
API token has been set.
CircleCI Host https://circleci.com
CircleCI host has been set.
Setup complete.
Your configuration has been saved to C:\Users\h.kameda\.circleci\cli.yml.

Trying to query our API for your profile name... Hello, harunobukameda@gmail.com.

これで初期セットアップ完了です。

3.`config.yml`のローカルベリフィケーション

では間違いを含む以下のファイルを作成してテストします。

config.yml

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run:
          name: "Install"
          commnd: npm install   # ← "command" のスペルミス（検出される）

workflows:
  build_and_test:
    jobs:
      - build

          commnd: npm install   # ← "command" のスペルミス（検出される）

commandがcommndになっていますね。
circleci config validate config.ymlを実行するといかが出力されます。

`circleci config validate` のエラーメッセージ

Error: config compilation contains errors: config compilation contains errors:
- ERROR IN CONFIG FILE:
- [#/jobs/build] 0 subschemas matched instead of one
- 1. [#/jobs/build] only 1 subschema matches out of 2
- | 1. [#/jobs/build/steps/1] 0 subschemas matched instead of one
- | | 1. [#/jobs/build/steps/1] expected type: String, found: Mapping
- | | | Shorthand commands, like checkout
- | | | SCHEMA:
- | | | type: string
- | | | INPUT:
- | | | run:
- | | | name: Install
- | | | commnd: npm install
- | | 2. [#/jobs/build/steps/1] extraneous key [run] is not permitted
- | | | when/unless step
- | | | Permitted keys:
- | | | - when
- | | | - unless
- | | 3. [#/jobs/build/steps/1/run] 0 subschemas matched instead of one
- | | | 1. [#/jobs/build/steps/1/run] expected type: String, found: Mapping
- | | | | SCHEMA:
- | | | | type: string
- | | | | INPUT:
- | | | | name: Install
- | | | | commnd: npm install
- | | | 2. [#/jobs/build/steps/1/run] required key [command] not found
- 2. [#/jobs/build] expected type: String, found: Mapping
- | Job may be a string reference to another job
- 3. [#/jobs/build] required key [type] not found

少しエラーが冗長で見づらいかな？という感じもありますけど、都度都度パイプラインを実行させるよりはもちろんはるかに簡単にエラーを検知できます。

このvalidateコマンドは設定ファイルの構文をチェックするため、コマンドの間違いなどは対象外です。それは別の記事でまた触れていきたいと思いますが、実行時のコマンドミスをローカルでテストしたい場合は、circleci local execute を使うと実際にジョブをローカルでシミュレーションできます（Dockerが必要です）。

例えば以下のファイルはvalidateは通ります。