2026年8月13日

CircleCIのOrbsを活用する方法（使い方・バージョン固定・安全な選び方）

バックアップ・監視

CircleCI の Orbs（オーブ）は、よく使うジョブ・コマンド・実行環境をパッケージにまとめ、config.yml から 1 行で呼び出せるようにする仕組みです。この記事では、Orbs の構成要素と基本の使い方、展開後の設定を確かめる方法、バージョンの固定、サードパーティ製 Orbs を使うときの安全確認、自作のインライン Orb までを解説し、設定ファイルを短く保ちながら中身を把握できる状態を目指します。

Orbs で何ができるのか

CI の設定を書いていると、「Node.js を入れて依存関係をキャッシュする」「AWS CLI をセットアップする」「Slack に結果を通知する」といった定型処理を、プロジェクトごとに何度も書くことになります。Orbs はこうした処理を再利用できる部品として公開・配布する仕組みで、CircleCI が公開している公式の Orbs のほか、パートナー企業やコミュニティが作ったものが Orb レジストリ（CircleCI Developer Hub）で検索できます。

Orb が提供する部品は主に 3 種類です。

commands: ジョブの中で使うステップのまとまり。例: 依存関係のインストールとキャッシュ
jobs: 実行環境とステップを含むジョブ全体。ワークフローから直接呼び出せます
executors: ジョブを動かす実行環境（Docker イメージなど）の定義

Orbs を使うには、設定ファイルの version が 2.1 である必要があります。2.0 のままだと orbs キーが認識されず、設定エラーになります。

基本の使い方

WordPress テーマのフロントエンド資産（CSS / JS）を Node.js でビルド・テストする例です。.circleci/config.yml に書きます。

version: 2.1

orbs:
  node: circleci/node@5.2.0

workflows:
  build-and-test:
    jobs:
      - node/test:
          version: '20.11'
          pkg-manager: npm

orbs の下で node という名前（エイリアス）を付けて Orb を読み込み、node/test のように「エイリアス/部品名」で呼び出します。node/test ジョブは、Node.js の実行環境の用意、依存関係のインストールとキャッシュ、npm test の実行をまとめて行います。

ジョブを丸ごと使うのではなく、自分のジョブの中で Orb のコマンドだけを使うこともできます。PHP のテストと組み合わせたいときはこちらのほうが柔軟です。

version: 2.1

orbs:
  node: circleci/node@5.2.0

jobs:
  build-assets:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - assets/dist

  php-lint:
    docker:
      - image: cimg/php:8.3
    steps:
      - checkout
      - run: find . -name '*.php' -not -path './vendor/*' -print0 | xargs -0 -n1 php -l

workflows:
  main:
    jobs:
      - build-assets
      - php-lint

cimg/ で始まるのは CircleCI が提供する実行環境用のイメージ（convenience images）です。タグの番号は例なので、採用時点で提供されているバージョンを Docker Hub や CircleCI のドキュメントで確認してください。Orb のジョブやコマンドが受け付けるパラメーター名・既定値も Orb のバージョンによって変わるため、上の例を写す前にレジストリのページで使うバージョンの説明を確認するのが確実な進め方です（2026年10月現在）。

展開後の設定を確認する

Orbs は便利な反面、設定ファイルに書かれていない処理が実行されるため、「実際に何が動いているのか」が見えにくくなります。CircleCI CLI を使うと、Orb を展開した後の設定や Orb のソースを手元で確認できます。

# 設定ファイルの構文チェック
circleci config validate

# Orb を展開した後の設定を表示
circleci config process .circleci/config.yml

# Orb の概要と、提供されるジョブ・コマンドの一覧
circleci orb info circleci/node@5.2.0

# Orb のソースそのものを表示
circleci orb source circleci/node@5.2.0

config process の出力を見ると、node/test の 1 行が具体的にどんな run ステップに展開されるかが分かります。キャッシュのキーが意図と違う、余計なステップが入っている、といった問題はここで見つけられます。プッシュしてから失敗を待つより早く原因にたどり着けるので、Orb を新しく入れたときや更新したときは一度確認しておくと安心です。

バージョンの指定方法

Orb のバージョンはセマンティックバージョニングで管理されています。指定の仕方によって、更新の取り込み方が変わります。

circleci/node@5.2.0 のように完全なバージョンを書くと、そのバージョンに固定されます。
circleci/node@5 のようにメジャーだけを書くと、5.x 系の最新が使われます。
@volatile は最新版を常に使う指定で、ある日突然挙動が変わる可能性があります。

本番のデプロイを含むパイプラインでは、完全なバージョンで固定し、更新は意図して行うのが安全です。固定すると更新を忘れがちになるため、定期的にレジストリで新しいバージョンと変更点を確認し、ブランチで試してから上げる運用にします。

サードパーティ製 Orbs を使うときの注意

Orbs はジョブの中で任意のコマンドを実行できます。つまり、そのジョブで使える環境変数やコンテキスト（デプロイ用の鍵、API トークンなど）にも Orb の処理からアクセスできるということです。導入前に次の点を確認してください。

作成者の種類: レジストリでは、CircleCI 公式、パートナー、コミュニティの区別が表示されます。コミュニティ製は便利なものも多い一方で、メンテナンスが止まっているものもあります。
ソースの確認: circleci orb source で中身を読み、外部からスクリプトをダウンロードして実行していないか、秘密情報を外部に送っていないかを確認します。
組織の設定: CircleCI の組織設定には、公式以外の Orbs の利用を許可するかどうかの項目があります（表記はバージョンで変わります）。既定では制限されている場合があるので、組織の方針に沿って設定します。
コンテキストの制限: 本番用の秘密情報はコンテキストに入れ、セキュリティグループなどで使えるユーザーやプロジェクトを絞ります。秘密情報が必要ないジョブにはコンテキストを渡さないようにします。

自作の Orb を使う

社内の複数プロジェクトで同じ処理を使い回したいときは、自分で Orb を作れます。いきなりレジストリに公開しなくても、設定ファイルの中に直接定義する「インライン Orb」で試せます。

version: 2.1

orbs:
  wp-tools:
    commands:
      php-lint:
        parameters:
          path:
            type: string
            default: "."
        steps:
          - run:
              name: PHP の構文チェック
              command: find << parameters.path >> -name '*.php' -not -path '*/vendor/*' -print0 | xargs -0 -n1 php -l

jobs:
  lint:
    docker:
      - image: cimg/php:8.3
    steps:
      - checkout
      - wp-tools/php-lint:
          path: wp-content/themes/my-theme

workflows:
  main:
    jobs:
      - lint

parameters で受け取った値は << parameters.path >> の形で埋め込みます。インライン Orb で使い勝手を確かめた後、複数のリポジトリで共有したくなったら、CLI で名前空間を作成してレジストリに公開します。公開した Orb は基本的に誰でも参照できるため、社内向けの処理はプライベート Orb（利用できるプランが限られる場合があります）や、設定ファイル内での再利用可能なコマンド定義で済ませる選択肢も検討してください。

うまく動かないときの確認順

**orbs が認識されない**: version: 2.1 になっているかを確認します。
パラメーターのエラー: 使っている Orb のバージョンで、そのパラメーター名が存在するかを circleci orb info で確認します。メジャーバージョンの更新でパラメーター名が変わることがあります。
Orb の読み込みが拒否される: 組織設定で公式以外の Orbs が許可されているかを確認します。
想定外の動き: circleci config process で展開後の設定を見て、実際のステップを確認します。

まとめ

Orbs は commands・jobs・executors を再利用可能な形にまとめたもので、version: 2.1 で使えます。
circleci config process や circleci orb source で、展開後の設定と中身を確認してから使います。
本番を含むパイプラインでは完全なバージョンで固定し、変更点を確認してから更新します。
サードパーティ製 Orbs は秘密情報にアクセスできる前提で、作成者・ソース・コンテキストの制限を確認します。
共通処理はインライン Orb で試してから、必要に応じて公開やプライベート Orb を検討します。