この記事では、 CircleCI の CI / CD 設定を複数プロジェクトで再利用できる形として集約管理するための「CircleCI URL Orb」について紹介します。

１つの開発チームが複数のプロジェクトを運用している場合、利用する技術スタックが共通化されがちです。それに伴い、自動テストやデプロイの設定なども似通った内容になることが多いです。そうなると新しいプロジェクトを立ち上げる際に、CI / CDの設定などをコピペする作業が発生し、手作業のコピーミスによる不具合なども起こり得ます。

このような似通った設定ファイルが分散配置される問題を軽減するのが、CircleCIのOrbです。CircleCI の orb は、再利用可能な設定パッケージで、複数プロジェクトで共通の設定を使い回したい場合に活用できます。

２つの設定共有方法: URL Orb と Registry Orb の違い

CircleCI には2種類の orb があります。

１つ目はRegistry Orb と呼ばれており、CircleCI Orb Registry に公開される orb です。circleci/node@5.0.2 のように namespace とバージョンで参照します。こちらはCircleCIやCodecovなどのベンダーが提供する「CI / CDのベストプラクティス」を簡単に入手するために利用することが多い仕組みです。ベンダーは自社のツールをCircleCIにてベストな形で利用してもらう手法としてRegistry Orbを公開することがあります。

２つ目のURL Orb は、その名の通りYAMLファイルを HTTPSで参照するタイプの orbです 。例えばGitHub リポジトリの raw URL などで直接参照できます。公開プロセスが不要な上、CircleCIとGitHubを連携する際に使われる認証情報が利用できるため、Privateリポジトリでも利用できます。

項目	URL Orb	Registry Orb
ホスト場所	任意の HTTPS URL	CircleCI Orb Registry
バージョン管理	なし（URL 参照）	セマンティックバージョニング必須
公開プロセス	不要	circleci orb publish が必要
適用場面	組織内での設定共有	広く公開・再利用する場合

チームや企業内で決定した CI / CDのベストプラクティスを共有する場合、URL orbを利用することをお勧めします。URLで簡単にシェアできるため、組織内での設定一元管理やプラットフォームチームによる標準設定の配布に適しているといえます。

CircleCIのURL Orbsを有効化する

URL orb を使用するには、CircleCIアカウントのあるOrganizationで allow list に URL プレフィックスを登録する必要があります。

Organization Settings → Orbs に移動し、「Allowed URL Orb prefixes」セクションで「Add」を選択してください。

Addボタンを押すと、モーダルでOrbの名前やURL Prefix、Auth フィールドが表示されます。GitHubリポジトリを利用する場合、URL Orbsを管理するリポジトリのURLをURL prefixに指定しましょう。ただしYAMLのRawファイルにアクセスできる必要があります。よってURLはhttps://raw.githubusercontent.com/your-org/のような形になることに注意しましょう。Privateリポジトリである場合は、AuthでGitHub Appによる認証などを設定してください。

Orbsに追加したものが表示されていれば、設定完了です。

URL Orbを作成する

利用する側の設定が完了したので、早速Orbを作ってみましょう。ちなみに作成方法については、元AWS / Cloudflareで現さくらインターネットの亀田さんもブログにて紹介されています。

Orbの作成自体にコマンドなどは特に必要ありません。YAMLファイルを作成し、共有したいコマンドやジョブを定義するだけです。以下に例として Node.js のユニットテストを実行する orb を紹介します。

# node-unit-test-orb.yaml
version: 2.1

description: Node.js unit test orb with coverage support

orbs:
  node: circleci/node@5.0.2

commands:
  unit_test:
    description: Install dependencies and run unit tests with coverage
    parameters:
      pkg-manager:
        type: enum
        enum: [npm, yarn, yarn-berry]
        default: npm
      test-command:
        type: string
        default: "npm run test:coverage"
      test-results-path:
        type: string
        default: "test-results"
      coverage-path:
        type: string
        default: "coverage"
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: << parameters.pkg-manager >>
      - run:
          name: Run unit tests with coverage
          command: << parameters.test-command >>
      - store_test_results:
          path: << parameters.test-results-path >>
          when: always
      - store_artifacts:
          path: << parameters.coverage-path >>
          when: always

このOrbには、unit_testというコマンドが実装されています。その名の通り、npmでテストコマンドを実行するものですが、それに加えてテストの実行結果やカバレッジレポートをアーティファクトなどへ保存するステップも整備してあります。

このようなYAMLファイルをリポジトリにいくつか作成し、Gitでコミットしておきましょう。orbs/ディレクトリにまとめておくと、ドキュメントや検証用のスクリプトなどを追加したくなったときに見通しが良くなります。

your-org/circleci-orbs/
├── README.md
└── orbs/
    └── node-unit-test-orb.yaml

余談: コマンドとジョブ、どちらで作成するか

Orbで共有できるものには、ジョブとコマンドなどがあります。この２つは似ていますが、設定方法やOrbを利用する側での使い方が少し異なりますので、簡単に整理しておきましょう。

環境等の設定もまとめて管理する場合はジョブとして定義する

Job はexecutor 、つまり実行環境なども含む実行単位です。以下の例では、テストのコマンドだけではなく、Nodeのバージョンなども指定されています。

# orb での定義
jobs:
  unit_test:
    docker:
      - image: cimg/node:18
    steps:
      - checkout
      - run: npm test

ジョブとして設定したものは、workflows の jobs: セクションから直接呼び出すことができます。これにより、プロジェクトごとに実行するDockerイメージのバラツキをなくすなど、強力に共通化されたタスクの定義が行えます。

# 呼び出し方（workflow から）
workflows:
  main:
    jobs:
      - my-orb/unit_test  # workflow の jobs で呼ぶ

コマンド実行手順などの共通化だけであれば、コマンドとして配布

Command はもう少し緩やかな共通化手法です。ジョブと異なり、実行環境などの設定は行いません。どの順番でコマンドを実行すべきかにフォーカスしたい場合に使います。

# orb での定義
commands:
  run_tests:
    steps:
      - checkout
      - run: npm test

こちらはworkflowsではなく job の steps: セクション内から呼び出します。executorの指定などは Orb利用側で行うため、ランタイムのバージョンなどのカスタマイズがやりやすくなります。

# 呼び出し方（job の steps 内から）
jobs:
  my-job:
    docker:
      - image: cimg/node:18
    steps:
      - my-orb/run_tests  # steps で呼ぶ

作成したOrbをプロジェクトで使用する

Orbの作成とpushが完了したら、いよいよプロジェクトで利用します。Orbを使う側のプロジェクトにある .circleci/config.yml で URL orb をインポートしましょう。

version: 2.1

orbs:
  test: https://raw.githubusercontent.com/your-org/circleci-orbs/main/orbs/node-unit-test-orb.yaml

jobs:
  run_tests:
    docker:
      - image: cimg/node:18
    steps:
      - test/unit_test:
          pkg-manager: npm
          test-command: "npm run test:coverage"

workflows:
  main:
    jobs:
      - run_tests

• 読み込みたいYAMLファイルのURL
• 利用したいコマンドやジョブの定義
• ジョブやコマンドに渡すパラメーター

これらを指定するだけで、共通化されたテストやビルドタスクを実行できるようになりました。

実際のPJでは、git tagしたバージョンなどをURLにしよう

簡単に試すため、今回はURLをmainブランチにあるYAMLファイルとしました。しかし実運用ではgit tagでバージョンを指定したものか、コミット SHA を含む URL を使うことをお勧めします。

これはOrb側のリポジトリが変更された場合に、意図せずCIパイプラインがfailするリスクを抑えることが目的です。「XXXX/MM/DDに更新されたOrbを使います」のような形でURL orbを読み込む設定にすることで、「何もしていないのにCIが壊れた」事態の発生を防ぐことができます。

試している中でハマったこと

勉強も兼ねて触っている中で、いくつかのトラブルがありました。慣れるまでハマることがありそうなので、記録として共有します。

“Cannot find a definition for command named …” エラー

steps の中で job を呼び出そうとしている場合に発生します。

# NG: job を steps 内で呼び出している
steps:
  - my-orb/unit_test  # unit_test が job として定義されている場合エラー

# OK: command を steps 内で呼び出す
steps:
  - my-orb/unit_test  # unit_test が command として定義されていれば OK

解決策として、steps から呼び出したい場合は command として定義してください。

“Orb not found” エラー

allow-list に URL prefix が登録されていない場合に発生します。Organization Settings → Orbs で allow-list を確認してください。

変更が反映されない

GitHub のキャッシュが原因の場合があります。ブランチ名を含む URL ではなく、コミット SHA を含む URL を使用すると確実でしょう。

# キャッシュされる可能性がある
orbs:
  test: https://raw.githubusercontent.com/org/repo/main/orb.yaml

# 確実に最新を取得
orbs:
  test: https://raw.githubusercontent.com/org/repo/abc1234/orb.yaml

まとめ

URL orb は、Registry orb と比較して手軽に作成・更新できる点が大きなメリットです。組織内での設定共有や、プラットフォームチームによる標準 CI/CD 設定の配布に最適といえるでしょう。

作成時のポイントをまとめると、command と job の違いを理解し、適切な方を定義することが重要です。また、柔軟性のために command と job の両方を提供することを検討し、パラメータには適切なデフォルト値を設定してください。

まずは小さな orb から始めて、徐々に機能を拡張していくのがおすすめです。

参考リンク

• CircleCI Orbs Overview
• Managing URL Orb Allow-lists
• Orb Authoring Process