CircleCI URL Orbsで組織横断のCI/CD設定標準化を実現させる方法

5つのマイクロサービスを運用するチームで、それぞれの .circleci/config.yml に同じデプロイ設定が250行ずつコピペされている——そんな状況に心当たりはありませんか？そして1つの設定を変更するたびに、5つのリポジトリすべてを修正し、レビューし、マージする作業に1時間以上を費やしていませんか？

CircleCI の URL Orb を使えば、共通設定を1箇所で管理し、各プロジェクトは1行で参照するだけで済みます。設定の重複を削減し、変更は1回のPRで全プロジェクトに反映できます。

本記事では、組織内での設定共有に最適な「URL Orb」の導入方法を解説します。

2種類のOrb：Registry OrbとURL Orb

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

1つ目は Registry Orb です。CircleCI Orb Registry に公開される Orb で、circleci/node@5.0.2 のように namespace とバージョンで参照します。CircleCI やサードパーティベンダーが提供する「CI/CDのベストプラクティス」を簡単に導入できる仕組みです。広く公開・再利用する場合に適しています。

2つ目が本記事で紹介する URL Orb です。YAML ファイルを HTTPS で直接参照するタイプの Orb で、GitHub リポジトリの raw URL などで参照できます。公開プロセスが不要なため、組織内での設定一元管理やプラットフォームチームによる標準設定の配布に適しています。

チームや企業内で決定した CI/CD のベストプラクティスを共有する場合には、２つ目のURL Orb の利用をお勧めします。

URL Orbの有効化手順

URL Orb を使用するには、CircleCI の Organization 設定で allow-list に URL プレフィックスを登録する必要があります。

まず Organization Settings → Orbs に移動しましょう。「Allowed URL Orb prefixes」セクションでURL Orbの管理を行います。右上にある「Add」ボタンをクリックしてください。

URL Orbを読み込むURLを設定するモーダルが表示されます。

Name には識別しやすい名前を入力してください。「Private URL Orbs」や「Platform Team Orbs」など、用途がわかる名前を付けましょう。

URL Prefix には Orb を管理するリポジトリの URL を指定します。GitHub を利用する場合、YAML の Raw ファイルにアクセスできる URL を指定する必要があるため、https://raw.githubusercontent.com/your-org/ のような形式になります。

Auth では認証方法を選択します。選択肢は None、GitHub OAuth、GitHub App、Bitbucket OAuth の4つです。Private リポジトリで URL Orb を管理する場合は GitHub App の利用を推奨します。OAuth 系の認証は組織メンバー全員に URL Orb の取得権限があることを前提としているため、権限が不足しているメンバーがいると取得に失敗するリスクがあります。GitHub App であればこの制限を回避できます。

詳細は公式ドキュメントの「Limitations and caveats」セクションをご確認ください。

URL Orbの制限事項

URL Orb には以下の制限があります。運用設計時に考慮してください。

• allow-list のエントリ数は 最大5件 までです。組織で利用する Orb の URL プレフィックスを整理し、できるだけ少ないエントリ数で管理できるよう設計しましょう
• 1つの config.yml から参照できる URL Orb は 最大50個 までです。直接参照だけでなく、Orb から別の Orb を参照する間接参照も含めてカウントされます
• URL Orb の参照階層は 最大5段階 までです。Orb A が Orb B を参照し、Orb B が Orb C を参照する……といった入れ子構造は5段階が上限となります
• 取得した Orb は 5分間キャッシュ されます。頻繁に更新される Orb を利用する際は、キャッシュの影響を考慮してください

詳細は公式ドキュメントの「Limitations and caveats」セクションをご確認ください。

URL Orbを実際に作成してみよう

allow-list の設定が完了したら、Orb を作成します。Orb の作成には特別なコマンドは不要で、YAML ファイルを作成し、共有したいコマンドやジョブを定義するだけです。

以下は Node.js のユニットテストを実行する Orb の例です。

# orbs/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 でテストを実行するだけでなく、テスト結果やカバレッジレポートをアーティファクトへ保存するステップも含まれています。パラメータにはデフォルト値を設定しているため、利用側では必要な項目だけをオーバーライドすれば済みます。

ディレクトリ構成

Orb ファイルはリポジトリ内の orbs/ ディレクトリにまとめておくと見通しが良くなります。

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

commandsとjobsの使い分け

Orb で共有できる要素には commands と jobs があります。両者は似ていますが、利用側での呼び出し方が異なります。

jobs は executor（実行環境）を含む完全な実行単位です。Docker イメージや Node.js のバージョンまで指定できるため、プロジェクト間で実行環境のばらつきをなくしたい場合に適しています。workflows の jobs: セクションから直接呼び出します。

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

# 利用側の呼び出し
workflows:
  main:
    jobs:
      - my-orb/unit_test

commands は実行環境を含まず、ステップのみを定義します。ランタイムのバージョンは利用側でカスタマイズしたい場合に適しています。job の steps: セクション内から呼び出します。

# Orb側の定義
commands:
  run_tests:
    steps:
      - checkout
      - run: npm test

# 利用側の呼び出し
jobs:
  my-job:
    docker:
      - image: cimg/node:20  # 利用側でバージョンを指定
    steps:
      - my-orb/run_tests

組織の標準化方針に応じて使い分けてください。実行環境まで厳密に統一したい場合は jobs、柔軟性を持たせたい場合は commands が適しています。

プロジェクトでの利用

Orb の作成と push が完了したら、プロジェクトの .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

orbs: セクションで URL を指定し、任意の名前（この例では test）を付けます。以降は test/unit_test のように「名前/コマンド名」の形式で呼び出せます。

URL orbsで参照するファイルのバージョンは固定しよう

上記の例では main ブランチを参照していますが、実運用では git tag やコミット SHA を含む URL を使用することを強く推奨します。

# NG: mainブランチを参照（Orb側の変更で意図せずCIが壊れるリスク）
orbs:
  test: https://raw.githubusercontent.com/your-org/circleci-orbs/main/orbs/node-unit-test-orb.yaml

# OK: タグを参照（明示的なバージョンアップまで変更されない）
orbs:
  test: https://raw.githubusercontent.com/your-org/circleci-orbs/v1.0.0/orbs/node-unit-test-orb.yaml

# OK: コミットSHAを参照（確実に固定）
orbs:
  test: https://raw.githubusercontent.com/your-org/circleci-orbs/abc1234def5678/orbs/node-unit-test-orb.yaml

Orb 側のリポジトリで変更が加わっても、利用側のプロジェクトは明示的にバージョンを更新するまで影響を受けません。「何もしていないのに CI が壊れた」という事態を防げます。

設定の重複を削減する効果

URL Orb を導入する前後で、どれだけ設定がシンプルになるかを比較してみましょう。

Orb導入前（150行）

version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:18
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}
      - run:
          name: Install dependencies
          command: npm ci
      - save_cache:
          key: v1-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules
      - run:
          name: Run unit tests
          command: npm run test:coverage
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: coverage
  
  deploy:
    docker:
      - image: cimg/aws:2023.03
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Build Docker image
          command: docker build -t myapp:${CIRCLE_SHA1} .
      - run:
          name: Push to ECR
          command: |
            aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_REPO
            docker tag myapp:${CIRCLE_SHA1} $ECR_REPO:${CIRCLE_SHA1}
            docker push $ECR_REPO:${CIRCLE_SHA1}
      # ... 以下100行以上のデプロイ設定が続く
workflows:
  main:
    jobs:
      - test
      - deploy:
          requires:
            - test

この設定を5つのマイクロサービスすべてにコピペしていると、合計750行の重複が発生します。

Orb導入後（30行）

version: 2.1

orbs:
  platform: https://raw.githubusercontent.com/your-org/circleci-orbs/v1.2.0/orbs/platform-orb.yaml

workflows:
  main:
    jobs:
      - platform/test
      - platform/deploy:
          requires:
            - platform/test

共通設定を Orb に集約することで、各プロジェクトは30行程度に削減できます。5つのマイクロサービス全体では150行まで圧縮され、600行の重複を削減したことになります。

URL Orbを試すときにありがちなトラブル

URL Orb の導入時によく遭遇するエラーと対処法を紹介します。

"Cannot find a definition for command named " エラーが発生した場合

steps の中で job を呼び出そうとしている場合に発生します。jobs として定義されたものは workflows から呼び出す必要があります

steps から呼び出したい場合は、Orb 側で commands として定義してください。

"Orb not found" エラーが発生した場合

allow-list に URL プレフィックスが登録されていない場合に発生します。Organization Settings → Orbs で allow-list を確認し、Orb の URL が登録済みのプレフィックスと一致しているか確認してください。

変更が反映されない

GitHub のキャッシュ、または CircleCI 側の5分間キャッシュが原因の可能性があります。ブランチ名を含む URL ではなく、コミット SHA を含む URL を使用すると確実に最新版を取得できます。

Registry Orb と URL Orb の使い分け

CircleCI には Registry Orb と URL Orb の2種類がありますが、用途によって使い分けましょう。

用途	推奨	理由
AWS/Slack/Kubernetesなど汎用的な統合	Registry Orb	circleci/aws-ecr@9.0 など公式Orbが充実
組織固有の標準設定	URL Orb	社内ベストプラクティスを反映
プライベートな設定	URL Orb	公開不要、認証でアクセス制御
迅速な更新が必要	URL Orb	Registry公開プロセス不要

基本方針:

• まずOrb Registryで公式Orbを探す
• 見つからない、または組織固有の要件がある場合に URL Orb を作成

組み合わせも可能:

orbs:
  aws: circleci/aws-ecr@9.0  # 公式Registry Orb
  platform: https://raw.githubusercontent.com/your-org/circleci-orbs/v1.0.0/orbs/platform-orb.yaml  # 組織のURL Orb

まとめ

URL Orb は Registry Orb と比較して手軽に作成・更新でき、組織内での設定共有に最適です。プラットフォームチームが標準 CI/CD 設定を配布し、各プロジェクトチームがそれを利用するという運用パターンを実現できます。

次のステップ

URL Orb を試してみる

1. Organization Settings → Orbs で allow-list に URL プレフィックスを追加
2. GitHub リポジトリに orbs/ ディレクトリを作成
3. 小さなコマンドから始める（例: checkout + npm ci + npm test）
4. git tag でバージョンを固定し、1つのプロジェクトから参照

より詳しく学ぶ

• 公式Orbsカタログ: CircleCI Orb Registryで汎用的な統合を探す
• Orb開発ガイド: Orb Authoring Processでさらに高度なOrbを作成
• 質問・フィードバック: CircleCI Discuss