🌟

CircleCI : URL Orbs ～公開処理不要の外部URLから呼びだせるシンプルな新しいOrb

2025/09/03に公開

過去複数の記事でOrbというCircleCIのデプロイワークフローにおける再利用可能なコンポーネントの利用方法や組織間での自作、再利用方法について触れてきました。

OrbはCircleCIのCLIを用いて作成を行いパブリック、ないしは組織専用のプライベートレジストリへの公開を行わなければ再利用は行えませんでした

circleci orb publish orb.yml testorb/testorb@dev:first

レジストリに登録されたOrbは以下の通りOrganizationに所属し、Privateなものは同じOrganizationでしか再利用が行えず、Publicなものは全CircleCIユーザーが利用可能となっています。

今回新しくリリースされたURL Orbsは、レジストリにあらかじめOrbを登録していなくても、Orb用ymlを公開しているURLがCircleCIのデプロイ環境からアクセス可能であれば、再利用可能なOrbとしてデプロイワークフローから呼び出し可能となります。

さっそくやってみる

1. Allowed URL Orb prefixes への登録

URL OrbsはCircleCIのデプロイワークフロー環境からアクセス可能なURLであればなんでも利用可能なわけではありません。あらかじめOrganizationの設定で読み込んでいいOrb配布用URLを許可しておく必要があります。これにより、CircleCIの一般利用者が自由に外部のOrbを読み込むことを制御し、CircleCIのOrganization管理者のみが外部URL Orbを認証する、という運用を作ることができます。

コンソールのOrganization Settings→Orbをクリックします。

Allowed URL Orb prefixesのAddをクリックします。

GitHubの場合、raw(生のyml)ファイルのダウンロード用URLを登録します。
今回登録するものはフルパスではなくprefixです。
https://raw.githubusercontent.com/h-kameda-sakura/apitest/
試したところこれ以上、下の階層ディレクトリや直接的なymlファイル名を登録すると正しく動作しませんでしたので、prefixとしてhttps://raw.githubusercontent.com/<organization>/<repository name>/を登録します。

外部の URL が改ざんされるリスクがあるため、信頼できるリポジトリを許可リストに登録し、Org 管理者のみが管理する運用を推奨します。

2. Orb用ymlの作成

orbs/greeting.ymlという名前のファイルを以下に作成します。

orbs/greeting.yml

# orbs/greeting.yml
version: 2.1
description: A greeting command orb with Node.js installation

commands:
  greet:
    description: Greet someone with a "hello" and install Node.js
    parameters:
      to:
        type: string
        default: World
      node_version:
        type: string
        default: "20"
        description: Node.js version to install
    steps:
      - run:
          name: Install Node.js
          command: |
            # Prereqs
            sudo apt-get update -y
            sudo apt-get install -y curl ca-certificates
            # Node.js (Ubuntu/Debian)
            curl -fsSL https://deb.nodesource.com/setup_<< parameters.node_version >>.x | sudo -E bash -
            sudo apt-get install -y nodejs

            # Verify
            echo "Node.js version: $(node --version)"
            echo "npm version: $(npm --version)"

      - run:
          name: Greet with Node.js
          command: |
            echo "Hello << parameters.to >>"
            echo "Node.js << parameters.node_version >> is now installed!"
            node --version

これはデプロイ環境にNodeをインストールします。同時に、このOrbを呼び出したデプロイワークフローからパラメータを受け取り実行結果としてそのパラメータを出力します。

3. デプロイパイプライン用config.ymlの改修

config.yml

# .circleci/config.yml
version: 2.1

orbs:
  # URL Orb を生で参照します（ブランチ名は main を想定）
  greeting: https://raw.githubusercontent.com/h-kameda-sakura/apitest/main/orbs/greeting.yml

jobs:
  demo:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - greeting/greet:
          to: "kameda-san"
          node_version: "20"

workflows:
  use-greeting:
    jobs:
      - demo

従来のレジストリに登録を行うOrbは以下の書式でした。

orbs:
  greeting: testorb/testorb@1.1.0

URL Orbでは以下となっています。

orbs:
  greeting: https://raw.githubusercontent.com/h-kameda-sakura/apitest/main/orbs/greeting.yml

あとは普通にパイプラインが実行されれば完了です。

さっそくやってみる

1. Allowed URL Orb prefixes への登録

2. Orb用ymlの作成

3. デプロイパイプライン用config.ymlの改修

Discussion