CircleCI で orb を自作する
前回の記事では、再利用可能な設定項目を外部設定(orb)として呼び出し繰り返し再利用行うことでconfig.ymlの記載を短縮させ、すっきりとした構成にする方法を紹介しました。
OrbはRegistryのサイトで公開されており、よくあるもの（例えばAWS CLIの初期セットアップや各種言語の初期設定、など）は公式で作成されたものが公開されています。
公式が作成し公開しているorbとは別に、orbは自作することが可能です。それをパブリックに公開することも可能ですし、CircleCIの特定Organization向けにプライベートな状態で公開しておけば、自社用の初期設定を纏めておくことが可能です。今日はorbを自作する手順を纏めます。
さっそくやってみる
1. 事前準備
まずはCircleCIのProjectがGitHubレポジトリと連携している状態にします。例えば以下の記事を参考にしてください。
Orbを自作する場合１点注意があります。接続を行うGitHubは単独アカウントではなくOrganizationでなければいけない、という制限があります。
CircleCIのOrganization Settingsで以下の通り接続先がOrganizationとなっている点に注意してください。
接続が完了したらOrganization IDをコピーしておきます。
次に左ペインのSecurityをクリックしAllow uncertified public orbsを有効化します。Privateのorbを作成する場合は、Allow private orbsも有効化します。
2. CLIのセットアップ
以下の記事に従いCircleCI CLIをセットアップします。
3. Orb の自作
まず以下のコマンドを実行して名前空間を作成します。
circleci namespace create testorb --org-id <your-organization-id>
<your-organization-id>は先ほど取得した値に置き換えます。
次に作成された名前空間にorbを作成します。
circleci orb create testorb/testorb
以下のファイルを作成します。
version: 2.1
description: A greeting command orb
commands:
greet:
description: Greet someone with a "hello".
parameters:
to:
type: string
default: World
steps:
- run: echo "Hello, << parameters.to >>"
orbとはworkflowが存在しないconfig.ymlのような物です。
以下を実行して作成されたorb.yml検証します。
circleci orb validate orb.yml
4. Orb の公開
ではこれから公開を行います。
circleci orb publish orb.yml testorb/testorb@dev:first
このコマンドによりorbは公開準備状態になります。公開するためには再度以下のコマンドを実行します。
circleci orb publish promote testorb/testorb@dev:first patch
firstの部分は開発チーム側で識別しやすいものであればなんでもOKです。例えば1.0.0でも大丈夫です。これで公開が行われました。以下のコマンドで一覧が確認可能です。
circleci orb list testorb
circleci orb list testorb
Orbs found: 1. Showing only certified orbs.
Add --uncertified for a list of all orbs.
testorb/hello (0.0.1)
In order to see more details about each orb, type: `circleci orb info orb-namespace/orb-name`
Search, filter, and view sources for all Orbs online at https://circleci.com/developer/orbs/
バージョンは0.0.1から上書きされるたびに数字が増えていきます。ドキュメント上はこのバージョンを例えば1.0.0などにそろえるパラメータは存在しないようです
minor と major オプション
patchではなくminorやmajorを使うことで明示的にバージョンを指定できないものの、ある程度の操作が可能です。例えば以下を実行してみます。
circleci orb publish promote testorb/testorb@dev:first major
初回のmajorバージョン公開でtestorb/testorb (1.0.0)となります。次にminorを実行するとtestorb/testorb (1.1.0)となります。
5. テスト
作成されたorbであるtestorb/testorb (1.1.0)はconfig.ymlから呼び出せます。
version: 2.1
# orbの読み込み
orbs:
greeting: testorb/testorb@1.1.0 # 実際のnamespaceとorb名に置き換えてください
# ワークフローの定義
workflows:
test-greeting:
jobs:
- greet-job
# ジョブの定義
jobs:
greet-job:
docker:
- image: cimg/base:stable
steps:
- greeting/greet:
to: "CircleCI" # パラメータを指定（省略可能、デフォルトは"World"）
このようにorbを呼び出すとCircleCIがorb.ymlの<< parameters.to >>に引き渡されHello Worldが表示されます。
6. Nodeのインストール
ではorb.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: |
# Node.jsのインストール（Ubuntu/Debian系）
curl -fsSL https://deb.nodesource.com/setup_<< parameters.node_version >>.x | sudo -E bash -
sudo apt-get install -y nodejs
# インストール確認
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
<< parameters.node_version >>で指定されたバージョンのNodeをインストールします。指定されない場合はデフォルトで20をインストールします。
ではこのorbを呼び出すconfig.ymlを以下に書き換えます。
version: 2.1
# orbの読み込み
orbs:
greeting: your-namespace/your-orb@1.0.0 # 実際のnamespaceとorb名に置き換えてください
# ワークフローの定義
workflows:
test-greeting:
jobs:
- greet-job
# ジョブの定義
jobs:
greet-job:
docker:
- image: cimg/base:stable
steps:
- greeting/greet:
to: "CircleCI" # パラメータを指定（省略可能、デフォルトは"World"）
node_version: "18" # Node.jsバージョン指定（省略可能、デフォルトは"20"）
こうすることでorb内部で指定されているNodeバージョンの20がconfig.ymlの18に上書きされます。
Discussion