この記事では、 CircleCI を利用して CI / CD パイプラインを構築する際の設定変更を簡単にテストする方法。特にGitを使わずにパイプラインを実行する方法について紹介します。この記事を読むことで、 CircleCI でのパイプラインを初めて構築する際、設定の調整などの試行錯誤が簡単に実行できるようになります。

CI / CDの設定変更のテストは大変

GitHub Action や CircleCI などのサービスでCI / CDを開始する際、最も手間と時間がかかるフェーズは、パイプラインの設定構築フェーズです。YAMLファイルを更新した後、Gitにコミットしてリモートにpushする。パイプラインの設定を確認するにはこのステップを毎回繰り返す必要があります。そして設定やYAMLの構文にミスが見つかると、ブラウザでログを調査してまた設定変更から Git の操作までをやり直すことになります。このフローは時間がかかるだけでなく、Gitの履歴が汚れてしまう問題もあります。「fix typo」「update config」といったテスト目的のコミットは残したくないですし、後からGitを操作してコミットを整理するのも手間がかかります。

実はCircleCIの場合、このようなCI / CD パイプライン構築の試行錯誤をVS Code上で完結できる拡張機能が公式でリリースされています。

CircleCI VS Code 拡張機能の概要

CircleCI VS Code 拡張機能は、CircleCI が公式に提供する開発ツールです。VS Codeを利用している場合、無料で利用することができます。

この拡張機能にはいくつかの機能が実装されています。

• ローカル上にある.circleci/config.ymlを利用したパイプラインの実行
• エディタ内でのYAMLや構文バリデーション
• パイプライン実行履歴やジョブ詳細のチェック
• etc..

定期的にアップデートも行われていますので、詳細については公式のドキュメントをご確認ください。

この拡張機能を利用することで、VS Codeから離れることなく CI / CD パイプラインの実行やテスト・デバッグなどが行えます。ブラウザに CircleCI のダッシュボードを開き、.circleci/config.ymlをコミット・プッシュするたびにエディタとブラウザを行ったり来たりする必要がなくなります。

CircleCI VS Code拡張機能のセットアップ手順

この拡張機能を利用するには、VS Codeの他にCircleCIのパーソナルAPIトークンが必要です。ここからは設定方法をstep by stepで紹介します。

VS Code への拡張機能インストール

まず VS Code を起動し、拡張機能のマーケットプレイスを開きましょう。検索バーに「circleci」と入力すると、公式の CircleCI 拡張機能が表示されます。

CircleCI に関連する拡張機能は複数見つかります。発行元が「CircleCI」であることを確認してからクリックしましょう。

Install ボタンをクリックするだけで追加自体は完了します。発行元への信頼確認ダイアログが表示される場合があります。「Trust Publisher & Install」を選択してインストールを進めましょう。

CircleCI との接続設定

拡張機能のインストールが完了すると、VS Code の左サイドバーに CircleCI のアイコンが追加されます。このアイコンをクリックしましょう。

初回起動時は「Log in to view your pipelines」というメッセージが表示されます。Log In ボタンをクリックすると、パーソナルAPIトークン の入力を求めるダイアログが開きます。

パーソナルAPIトークン は CircleCI の Web UI から作成します。CircleCI にログインし、右上のユーザーアイコンから User Settings を選択してください。左側のメニューから Personal API Tokens を選び、Create New Token ボタンをクリックします。作成されたトークンは一度しか表示されないため、必ずコピーして保存しておきましょう。

VS Code に戻り、コピーした Personal API Token を入力フィールドに貼り付けます。

Connect to CircleCI ボタンをクリックすると、接続が完了し「You are connected to CircleCI」というメッセージが表示されます。なお、もしCircleCI Server を利用している場合は、「I’m a CircleCI Server customer」のチェックボックスをオンにしてください。

これでVS CodeとCircleCIの接続が完了しました。次はプロジェクトの連携を行います。

プロジェクトのセットアップ

VS Code で参照する CircleCI プロジェクトをセットアップしましょう。GitHubリポジトリが必要となりますので、新しく用意したい場合は、README.mdなどがあるだけのシンプルなリポジトリを用意しておきましょう。

CircleCIのダッシュボードにて、Projects ページを開き、セットアップしたいリポジトリの Set up ボタンをクリックします。

「Select your config.yml file」というダイアログが表示され、3つのオプションが提示されます。自前の設定ファイルがない場合は、Fasterを選びましょう。このオプションを選ぶと、CircleCI が自動的にサンプルの config.yml を含むプルリクエストを作成してくれます。

Set Up Project ボタンをクリックしましょう。CircleCI上でプロジェクトが作成されると同時に、GitHub側にプルリクエストが作成されます。これをマージして、 main ブランチに反映させておきましょう。次に、ローカル環境でリポジトリをクローンし、VS Code で開いてください。

git clone https://github.com/your-username/your-repository.git
cd your-repository
code .

VS Code で CircleCI パネルを開くと、PIPELINES セクションに「No project detected – Click here to sele…」と表示されています。

このメッセージをクリックし、リストから先ほどセットアップしたプロジェクトを選択します。

プロジェクトが正常に選択されると、PIPELINES セクションにプロジェクト名とパイプライン実行履歴が表示されます。

これでプロジェクトのセットアップは完了です。

unversioned configuration の設定

VS Code 拡張機能を使ってローカルの設定ファイルでパイプラインを実行するには、CircleCI 側で特別な設定を有効にする必要があります。この機能は「unversioned configuration」と呼ばれています。

CircleCI の Web UI を開き、Organization Settings にアクセスします。左側のメニューから Advanced を選択してください。

ページをスクロールすると、「Allow triggering pipelines with unversioned config」という設定項目が表示されます。これはバージョン管理されていない（ = Gitにコミットされていない）設定ファイルを使ったパイプラインのトリガーを許可するかどうかを選択できる画面です。

今回はこの設定をオンに変更しましょう。

この設定はデフォルトで全プロジェクトに対してオンになっていますが、プロジェクトごとにオプトアウトも可能です。特定のプロジェクトで無効にしたい場合は、Project Settings > Advanced > Allow triggering pipelines with unversioned config から設定を変更できます。

ローカルで編集した設定でCircleCIのパイプラインを実行する

それでは実際に、ローカルで編集した設定ファイルを使ってパイプラインを実行してみましょう。

1: config.yml を編集する

まずはVS Code でプロジェクトの .circleci/config.yml を開きましょう。CircleCI が自動生成したサンプル設定が記載されているはずです。ここでは以下のような変更を加えてみましょう。

jobs:
  say-hello:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: "Say Good Bye"  # 元は "Say hello"
          command: "echo good bye"  # 元は "echo Hello, World!"

run ステップの name を「Say hello」から「Say Good Bye」に変更し、command を「echo Hello, World!」から「echo good bye」に変更しています。実際には細かなコマンドを設定していくことになりますが、今回は「GitHub上にある設定と異なるコマンドを実行すること」が目的なので、シンプルにいきましょう。

ここでのポイントは、Gitへのコミットやプッシュは行わず、保存だけ行うことです。

2: RUN パネルからの実行

保存できたので、早速 CircleCI のパイプラインを実行しましょう。VS Code の CircleCI パネルで RUN セクションを確認してください。unversioned configuration の設定を有効にしていれば、ここに実行可能なプロジェクトが表示されているはずです。

接続したプロジェクトもしくはリポジトリ名（今回はdemo-cci-vscode）をクリックしましょう。すると実行可能なジョブなどの情報が表示されます。

「Run local config on a remote branch of your choice」というオプションが表示されています。横にある再生ボタンをクリックしましょう。リモートブランチを選択するダイアログが開きますので、パイプラインを実行するブランチを選びましょう。そのブランチの最終コミットが表示されていますので、もしコミットが古いと思った場合は、pushして同期するなどしておきましょう。ここではorigin/mainを選択します。

最後に確認ダイアログが表示されます。ブランチ名の入力を求められますので「main」と入力しましょう。Enter キーを押すとジョブが開始されます。

3: 実行結果の確認

パイプラインのトリガーが成功すると、VS Code の PIPELINES セクションや CircleCI の Web UI に新しく実行されたパイプラインが表示されます。ダッシュボードの方を見てみると、最後のステップがローカルで保存した「Say Good Bye」に変わっていることがわかります。

このようにVS Code 拡張機能を利用すれば、Git にコミットしていないローカルの変更を CircleCI 上で実行することができます。VS Code側で実行結果も確認できますので、設定の変更からテスト実行・結果の調査までを VS Code でほぼ完結させたワークフローが作れます。Gitへのコミットやプッシュも不要になりますので、その分のタイムラグや作業ステップの削減・気持ち的なストレス軽減なども期待できそうです。というかこの機能 CircleCI 入る前に知りたかったです。

設定ファイルのバリデーションにも対応

VS Code 拡張機能には他にも機能があります。パイプラインを作成・変更する際に助かる機能としては、他にもエディタ内でのバリデーション機能があります。YAML のバリデーションがエディタ内で実行されるため、構文エラーをコミット前に発見できます。

これらの機能を活用し、CircleCIのパイプライン設定作業をできるだけストレスなく実行できるようになります。特に初期はうまく動かすだけでなく、コスト効率の調整なども必要になりますので、頻繁にテスト実行することが考えられます。そのような場合、VS Code の拡張機能は効率化にかなり貢献してくれそうです。

拡張機能を利用したパイプライン構築作業の注意点

便利な機能ではありますが、適切に運用しなければセキュリティリスクなどが発生します。最後に触っていて感じた注意すべき点についてまとめました。

unversioned configは作業時のみオンにする

unversioned configuration 機能をオンにし続けることは推奨されていません。公式ドキュメントには、「Warning: running pipelines with unversioned configuration can cause security vulnerabilities.」と記載されています。これはバージョン管理されていない設定ファイルでパイプラインを実行すると、脆弱性のあるジョブを実行しやすくなる問題があるためです。詳細については、公式ドキュメント（https://circleci.com/docs/guides/toolkit/vs-code-extension-overview/#security-implications）を参照してください。

そのため、unversioned configuration を許可する設定は、パイプラインを構築・変更する際にのみオンに設定し、それ以外の時間帯はオフにしておく必要があります。常時有効にしておくのではなく、必要な時だけオンにするという運用を徹底しましょう。

複数人での調整時は、実行対象のブランチを個別に用意しよう

バージョン管理されていない設定でパイプラインを実行するため、チームで共有するブランチや本番ブランチに対するパイプライン実行はお勧めしません。万が一意図しないビルドがデプロイされるリスクもありますし、その場合の設定ファイル調査が困難になります。必ずテスト用のブランチを用意して作業しましょう。

また、同時に複数人でCircleCIの設定を調整する場合は、テスト用のブランチを個別に用意しましょう。バージョニングされていないパイプラインをそれぞれが実行すると、どのパイプライン実行が誰の変更かがわかりにくくなり、自分の検証している内容が正しく動作しているのかどうかなどの開発におけるフィードバックサイクルがうまく回らなくなります。

最後に、設定が安定している既存プロジェクトで、軽微な修正のために毎回 unversioned configuration を使うのも推奨されません。リソースクラスの変更だけなどの小さな変更であれば、通常の Git ワークフローで十分です。拡張機能は、試行錯誤が多く発生する場面で真価を発揮します。

まとめ

CircleCI の VS Code 拡張機能は、パイプライン設定の試行錯誤を大幅に効率化するツールです。ローカルで編集した設定ファイルを Git にコミットすることなく CircleCI 上で実行できるため、開発速度が向上し、リポジトリ履歴も綺麗に保たれます。

ただし、unversioned configuration にはセキュリティリスクが伴います。公式ドキュメントに記載されている警告を理解し、必要な時だけ機能をオンにするという運用を徹底することが重要です。

この拡張機能を適切に活用すれば、CircleCI の設定調整作業は大きく改善されるでしょう。新規導入時や大規模な設定変更時には特に有用です。効率性とセキュリティのバランスを意識しながら、自身の開発ワークフローに組み込んでみてください。

https://circleci.com/docs/guides/toolkit/vs-code-extension-overview/#install-the-vs-code-extension