この記事では、CircleCIでCI / CDパイプラインを構築する際の「パイプライン構築ステップ」を手早く効率的に進める方法を紹介します。初めてCircleCIを試す方やCI/CDの設定を更新したいと考えられている方にとって、ストレスなく試行錯誤を行う方法として参考にしていただければと思います。
こんにちは、CircleCIのSenior Field Enginner 岡本です。今回よりこちらのアカウントで、CircleCIのユースケースや活用法・そしてCI / CDに関する様々な情報をお届けしていきます。
CI / CD パイプライン構築時のトライ＆エラーは時間がかかる？
CI / CDパイプラインを新しく構築する・更新する際、「パイプラインがちゃんと動くかどうか」のテストには思いのほか時間がかかります。これは設定ファイルを編集した後、実際のCI / CDパイプラインを動かしてみないと変更が正しく反映されているかチェックできないためです。
config.ymlを編集し、git commitしてpushし、CircleCIのダッシュボードで結果を確認する。構文エラーや設定ミスが見つかれば、また修正してcommit、pushそして確認...
このサイクルを何度も繰り返すことになります。この試行錯誤が原因で、Gitの履歴が「fix typo」「update config」「test ci」といったコミットで埋め尽くされることもあります。後からコミットを整理することはできますが、コミット整理の作業が追加で発生するのは効率的な環境とは言いにくいです。
頻繁に行う作業ではないため、そのタイミングだけ頑張ってどうにかする・・・こともできますが、より効率的な構築・テスト方法を知ることでミスが発生するリスクや作業ストレスを軽減させることができます。
この手間を軽減するために活用できるのが、CircleCI公式のVS Code拡張機能が提供する「ローカル設定でのパイプライン実行」機能です。
CircleCI公式のVS Code拡張機能について
CircleCIが提供するVS Code拡張機能は、VS CodeとCircleCIを接続してCI/CDパイプラインの管理やテスト、設定の変更などをVS Code上から行えるようにするツールです。
VS CodeのMarket Placeから無料でDLできます。
設定方法や機能の紹介などをチェックされたい方は、CircleCIのドキュメントをご覧ください。
この拡張機能を追加することで、git pushすることなく変更したconfig.yamlを利用したパイプラインのテスト実行ができます。
VS Code拡張機能でのテスト実行機能について
CircleCI VS Code拡張機能には、Gitにコミットしていないローカルのconfig.ymlを使って、CircleCIのパイプラインを実行する機能があります。
この機能を利用することで、VS Code上で編集中のconfig.ymlファイルを利用してCircleCIの本番インフラ上でパイプラインを実行できます。CircleCI CLIを利用してローカルでジョブをテスト実行することもできますが、この拡張機能を使った場合は、実際のCIパイプラインを動かせることが特徴です。
この機能を使ってパイプラインを事前にテストおくことで、「git pushしてみたらCIパイプラインが思っていた通りに動かなかった」「構文エラーを見落としていたので、修正をコミットしてpushする必要が出た」などの問題を予防することができます。
CircleCI拡張機能をVS Codeにインストールする
ここからはこの拡張機能を使って、ローカルからパイプラインのテスト実行を行う方法を紹介します。
ステップ1：VS Code拡張機能のインストール
VS Codeの拡張機能マーケットプレイスで「circleci」と検索しましょう。
発行元が「CircleCI」である公式拡張機能をインストールします。Install ボタンをクリックするだけで追加自体は完了します。
https://marketplace.visualstudio.com/items?itemName=circleci.circleci
インストールが完了すると、VS Codeの左サイドバーにCircleCIのアイコンが追加されます。
これで拡張機能のインストールは完了です。次はCircleCIアカウントとの接続を行います。
ステップ2：パーソナルAPIトークンの設定
拡張機能とCircleCIの連携はAPIトークンを利用して行います。CircleCIのダッシュボードから、パーソナルAPIトークンを取得しましょう。
パーソナルAPIトークンはCircleCIダッシュボードの「User Settings > Personal API Tokens」から発行できます。
APIトークンに名前をつけることができます。
「VS Code拡張用」のように後から識別できる名前をつけておきましょう。
APIトークンを発行したら、VS CodeのCircleCI拡張機能から接続設定を行います。VS CodeのタブからCircleCIパネルを開きましょう。「Log In」ボタンをクリックすると、APIトークン入力画面が表示されます。
ここで先ほど作成したAPIトークンをペーストしましょう。
CircleCI Serverをご利用中の場合は、「I'm a CircleCI Server customer」チェックボックスをオンにしましょう。
「Connect to CircleCI」ボタンをクリックして接続が完了すると、次のような完了画面が表示されます。
これでVS CodeとCircleCIの接続が完了しました。次はプロジェクトの連携を行います。
ステップ3：unversioned configurationの一時的な有効化
この機能を使うには、CircleCIの組織設定で「Trigger pipelines with unversioned config」オプションを有効にする必要があります。
CircleCIダッシュボードから「Organization Settings」にアクセスします。左メニューから「Advanced」を選択し、「Allow triggering pipelines with unversioned config」をオンに変更しましょう。
これは「バージョン管理されていない（ = Gitにコミットされていない）設定ファイルを使ったパイプラインのトリガーを許可するかどうか」を選択する機能です。「意図しない設定ファイルによるパイプラインの実行ができてしまう」というリスクが発生することにご注意ください。
Warning: running pipelines with unversioned configuration can cause security vulnerabilities
https://circleci.com/docs/guides/toolkit/vs-code-extension-overview/#security-implications
そのため、この「unversioned configuration」設定については、パイプラインの構築や変更を行う際だけオンにして、通常は無効化しておくことを推奨します。
この設定は組織管理者のみが変更できます。組織管理者でない場合は、管理者に依頼してください。また、組織全体に対してのオンオフを制御することになります。特定のプロジェクトで無効にしたい場合は、Project Settings > Advanced > Allow triggering pipelines with unversioned config から設定を変更しておきましょう。
ステップ4: VS Code拡張機能とCircleCIのプロジェクトを接続する
最後にVS Codeの拡張機能から接続したいCircleCIプロジェクトを選択しましょう。
VS Code で CircleCI パネルを開くと、PIPELINES セクションに「No project detected – Click here to sele…」と表示されています。
このメッセージをクリックし、リストから接続したいプロジェクトを選択します。
プロジェクトが正常に選択されると、PIPELINES セクションにプロジェクト名とパイプライン実行履歴が表示されます。
これでプロジェクトのセットアップは完了です。
VS CodeからCircleCIのパイプラインを実行する
セットアップが完了しましたので、実際に使ってみましょう。
config.ymlを編集する
VS Codeでプロジェクトの.circleci/config.ymlを開き、任意の変更を加えます。ここでのポイントは、Gitへのコミットは行わず、ファイルを保存するだけという点です。
jobs:
say-hello:
docker:
- image: cimg/base:current
steps:
- checkout
- run:
name: "Say Good Bye" # 変更箇所
command: "echo good bye"
RUNパネルから実行する
VS CodeのCircleCIパネルで「RUN」セクションを確認します。接続したプロジェクト名が表示されているはずです。
プロジェクト名をクリックすると、「Run local config on a remote branch of your choice」というオプションが表示されます。再生ボタンをクリックしましょう。
リモートブランチを選択するダイアログが開きます。ここでパイプラインを実行するブランチを選びます。そのブランチの最終コミットが表示されていますので、もしコミットが古いと思った場合は、pushして同期するなどしておきましょう。ここではorigin/mainを選択します。
最後に確認ダイアログが表示されます。ブランチ名の入力を求められますので「main」と入力しましょう。Enter キーを押すとジョブが開始されます。
実行結果を確認する
パイプラインが実行されると、VS CodeのPIPELINESパネルやCircleCIのWeb UIに結果が表示されます。ローカルで保存した変更内容が反映されていることを確認できます。
このように、Git pushやコミットなしで、ローカルの変更をCircleCI上でテストできます。
新規プロジェクトやパイプラインのセットアップで活用する
パイプラインを新規で作成する際、この拡張機能を使うことで設定作業やパイプラインのデバッグが効率化します。ジョブの定義やExecutorなどの選択にコマンド等のカスタマイズなど、何度も調整が必要になることが多いフェーズですので、VS Code拡張機能を使ってローカルから試行錯誤を繰り返しましょう。
一方で普段のCI / CDパイプライン実行に使うことはお勧めできません。これはGitで管理されていない設定ファイルによってパイプラインが実行されるため、「本当にやるべきテストやチェックが完了しているか」の確認ができなくなるためです。あくまでCIパイプラインそのものやconfig.ymlファイルの変更を行う際のテストツールとしての利用にとどめ、普段の開発フローでは必ずGitにコミットされた設定ファイルを使ったパイプラインによるチェックを行うようにしましょう。
安全なパイプライン実行と設定ファイル作成・変更を効率化するポイント
ルール1：作業時のみ有効化し、終了後は無効化する
unversioned configuration設定は、パイプラインを構築・変更する作業中のみオンにし、作業が完了したら必ずオフに戻してください。常時有効にしておくと、意図しないパイプライン実行のリスクが高まります。
ルール2：共有ブランチや本番ブランチへの実行を避ける
この機能では、任意のブランチに対してパイプラインを実行できます。しかし、mainブランチやdevelopブランチなど、チームで共有しているブランチに対して使用することは避けてください。意図しないデプロイを回避するためにも、この機能を使ったCIパイプラインの実行は、専用のブランチに対して行うようにしましょう。
ルール3：複数人で作業する場合は個別ブランチを使用する
チームで同時にCI設定の調整を行う場合、各メンバーが個別のテスト用ブランチを使用してください。同じブランチに対して複数人がunversioned configurationでパイプラインを実行すると、どの実行が誰の変更によるものかが判別できなくなります。
バリデーション機能も活用する
VS Code拡張機能には、パイプラインを実行する前に設定ファイルの問題を検出するバリデーション機能も搭載されています。
YAMLの構文エラーや、CircleCI固有の設定ミス（存在しないリソースクラスの指定、非推奨パラメータの使用など）をエディタ内で検出できます。パイプラインを実行する前にこれらのエラーを修正できるため、無駄な実行を減らせます。
まとめ
CircleCI VS Code拡張機能を活用することで、CI/CD設定の試行錯誤を大幅に効率化できます。
この機能の価値は、単に「Git pushが不要になる」だけではありません。ローカルの変更をCircleCIの本番インフラで即座に検証できる点が本質的な強みです。環境差異による問題を気にすることなく、設定の調整に集中できます。
SSHデバッグ機能と並び、CircleCIが提供する開発者体験向上機能の一つとして、ぜひ活用してみてください。
この機能を紹介してくださっている方のブログ