Orb の作成プロセス

クラウド

Server v4.x

Server v3.x

このページの内容

はじめに

この Orb 作成ガイドは、 Orb の概要と Orb の作成の概要のドキュメントを読み、名前空間を宣言していることを前提にしています。これらが完了していれば、Orb の作成を開始できます。

初めて Orb を記述する方も、本番レベルで用意したい方も、 Orb 開発キットを使って Orb の開発を始めることをお勧めします。または、Orb は再利用可能な設定をパッケージにしたものなので、単体の yaml ファイルとして Orb を手動で記述し、 CircleCI Orb 用の CLI を使用してパブリッシュすることも可能です。

Orb 開発キット

Orb 開発キットは、相互に連携する複数のツールをセットにしたものです。キットを使うと CircleCI でのテストとデプロイが自動化されるため、Orb の開発プロセスが簡易化されます。 orb init コマンドにより Orb 開発キットを使用できます。このコマンドは、テンプレートに基づいて新しい Orb プロジェクトを開始します。このテンプレートはキット内の他のツールを使って Orb を自動的にテストしデプロイします。

Orb 開発キットは、次の要素で構成されています。

Orb テンプレートは、CircleCI の Orb プロジェクトテンプレートを含むレポジトリで、orb init により自動的に取り込まれ変更されます。

CircleCI CLI には、このキットと連動するように設計された 2 つのコマンドが含まれています。 orb init コマンド により、新しい Orb プロジェクトが開始され、orb pack コマンドにより、Orb ソースが一つの orb.yml ファイルにパッケージ化されます。

orb tools orb は、Orb を作成するための Orb です。

Orb の作成、テスト、パブリッシュ

下記の手順に従って、Orb 開発キットを使って独自の Orb を作成、テスト、パブリッシュすることができます。

はじめよう

Orb 開発キットを使って新しい Orb の作成を始めるには、以下の手順を実行します。最初に行うのは、 GitHub.com でのリポジトリの新規作成です。

GitHub 上の組織 (Organization) が、Orb の作成先となる CircleCI の名前空間のオーナーになります。開始するにあたり、下記動画でも詳細をご確認いただけます。組織が個人のもので、ご自身が名前空間のオーナーであれば、問題ありません。

新しい_空の_ GitHub リポジトリを作成します。

リポジトリの名前は、特に重要ではありませんが、”myProject-orb” のような分かりやすい名前を付けることをお勧めします。

注: リポジトリは完全に空にしてください。 “README.md を追加する”、”ライセンスを選ぶ” といったオプションのチェックはすべて外してください。

必要な項目の設定が終わると、新しいリポジトリの内容を確認するページが開き、生成された Git の URL が表示されます。この URL をメモしておいてください。手順 4 で必要になります。 URL は SSH か HTTPS を選択できます。どちらを選択しても認証を行えます。

注: Orb 用にローカルディレクトリを作成する必要がありますが、Orb リポジトリをプルする必要はありません。このプロセスはorb init プロセスで完了するため、その前にこのリポジトリをプルすると問題が発生します。
CircleCI CLI を更新します。

最新バージョンの CircleCI CLI を使用していることを確認してください。 v0.1.17087 以降の CLI を使用している必要があります。
```
 $ circleci update

 $ circleci version
```
Orb を初期化します。

ターミナルを開き、orb init CLI コマンドを使用して、新しい Orb プロジェクトを初期化します。

CircleCI Server をご利用の場合は、</code>–private</code> フラグが使われており、Orb がインストール環境内でプライベートになっていることを確認してください。

パブリック Orb を初期化する場合:
```
 circleci orb init /path/to/myProject-orb
```
プライベート Orb を初期化する場合:
```
 circleci orb init /path/to/myProject-orb --private
```
Orb は一旦初期化されると、パブリックからプライペートに、またはその逆に変更することはできません。 プライベート Orb を作成したい場合は、必ず --private フラグをつけてください。

circleci orb init コマンドを、Orb プロジェクト用に作成して初期化するディレクトリを付けて呼び出します。このディレクトリと Git のプロジェクトリポジトリには、同じ名前を使用することをお勧めします。
Orb の完全自動セットアップオプションを選択します。
```
   ? Would you like to perform an automated setup of this orb?:
       ▸ Yes, walk me through the process.
   No, I'll handle everything myself.
```
手動オプションを選択した場合は、手動による Orb の作成プロセスで Orb をパブリッシュする方法を参照してください。

完全自動オプションを選択すると、 Orb-Template がダウンロードされ、カスタマイズした設定内容が自動的に反映されます。プロジェクトは CircleCI でフォローされ、自動化された CI/CD パイプラインが含められます。

CI/CD パイプラインの詳細については、 Orb のパブリッシュを参照してください。

または、 Orb テンプレートをダウンロードするだけの便利な方法を選ぶ場合は、「すべて手動で行う」を選択します。
指示に従って、Orb を設定し、セットアップを進めます。

バックグラウンドでは、入力内容に基づいてorb init コマンドが Orb テンプレートをコピーし、カスタマイズを実行します。各ディレクトリにある詳細な README.md ファイルには、それぞれのディレクトリのコンテンツに関する有益な情報が記載されています。手順 1 で取得したリモート Git リポジトリの URL も、入力が求められます。

Orb テンプレートには、完全な CI/CD パイプライン (詳細は、 Orb のパブリッシュプロセスを参照) が含まれており、Orb のパッケージ化、テスト、パブリッシュが自動的に実行されます。

セットアッププロセスでは、パーソナル API トークンを orb-publishing コンテキストに保存するかどうかを尋ねられます。 Orb の開発版と安定版をパブリッシュするためには、このトークンを保存しておくことが必要です。これまでに Orb を作成したことがある場合は、コンテキストが既に存在するためこの手順はスキップできます。
コンテキストが制限されていることを確認します。

[Organization Settings (組織設定)] > [Contexts (コンテキスト)] に移動して、コンテキストを制限します。

Orb のセットアップが完了したら、orb-publishing という新しいコンテキストが表示されます。この orb-publishing をクリックして、_セキュリティグループ_を追加します。セキュリティグループを使うと、ジョブのトリガーを許可されたユーザーだけにアクセスを制限することができます。プライベートのパーソナル API トークンにアクセスできるのも、これらのユーザーだけです。

詳細については、「コンテキストのガイド」を参照してください。
変更を Github にプッシュします。

このセットアッププロセスの間に、orb initコマンドは、自動 Orb 開発パイプラインを準備するための手順を実行します。 CLI が処理を続行し、circleci.com でプロジェクトを自動的にフォローするには、その前に、CLI によって生成された修正済みのテンプレートコードがリポジトリにプッシュされている必要があります。これを実行するよう要求されたら、別のターミナルから以下のコマンドを、「default-branch」を実際のデフォルトブランチの名前に置き換えて実行します。
```
 git push origin <default-branch>
```
完了したら、元のターミナルに戻って、変更がプッシュされたことを確認します。
セットアップを完了します。

変更がプッシュされたら、ターミナルに戻り、セットアッププロセスを続けます。 CLI が CircleCI のプロジェクトを自動的にフォローし、同じコードで Orb をビルドしテストするパイプラインのトリガーを試みます。

CircleCI 上でプロジェクトのビルドへのリンクが表示され、全パイプラインを見ることができます。また、 CLI によって自動的に ` alpha という名前の新しい開発ブランチに移行されたことも確認できます。ブランチ名は何でもかまいません。alpha`だけで作成する必要はありません。
ダイナミックコンフィグを有効にします。

CircleCI ではダイナミックコンフィグを使用しているため、まずこの機能を有効にする必要があります。最初のパイプラインでは「この機能は有効になっていません。」というエラーメッセージを受け取ります。

ダイナミックコンフィグ入門ガイドに従って、CircleCI でご自身の Orb の Project Settings を開き、Advanced に行き、Enable dynamic config using setup workflows ボタンをクリックします。

有効化されると、その後のプロジェクトへのすべてのコミットは全パイプラインを介して実行され、Orb を実行します。この時点で、パイプラインを手動で再実行することはできますが、現時点ではサンプルコードのみを使用しているため、必要ありません。
Orb を作成します。

デフォルト以外のブランチから (セットアップ時に alphaブランチに自動的に移動します)、サンプル Orb コードを好みに合わせて変更します。 _プッシュする_たびに、Orb が自動的にビルドおよびテストされます。

Orb コンポーネントのテスト方法を確認し、Orb の変更に伴ってテストを変更するには、必ず .circleci/test-deploy ファイルを参照してください。 Orb のテストに関する詳細は、 Orb のテストに関するドキュメントを参照してください。

最初の本番バージョンの Orb をデプロイする準備ができたら、「 Orb のパブリッシュプロセス」ガイドで変更事項のデプロイに関する情報を参照してください。

Orb の記述

Orb の作成を始める前に、デフォルト以外のブランチにいることを確認してください。通常は、alpha ブランチで Orb の作業を始めることをお勧めします。

$ git branch

* alpha
  main

circleci orb init コマンドを実行すると、自動的に alpha ブランチに移動し、リポジトリに .circleci ディレクトリと src ディレクトリが作成されます。

例: Orb プロジェクトの構造

タイプ	名前
	.circleci
	.github
	src
	.gitignore
	LICENSE
	README.md

Orb のソース

src ディレクトリに移動すると、含まれているセクションを確認できます。

例: Orb プロジェクトの “src” ディレクトリ

タイプ	名前
	commands
	examples
	executors
	jobs
	scripts
	@orb.yml

上記のディレクトリは、作成した Orb に含まれる Orb コンポーネントを表しています。 @orb.yml は Orb の root としての役割を果たします。 Orb の yaml コンポーネントを表すディレクトリに加えて、 ‘ scripts’ ディレクトリも表示されます。このディレクトリには、コンポーネントに挿入するコードを保存できます。

src 内の各ディレクトリは、再利用可能な設定のコンポーネントタイプに対応しており、Orb から追加や削除することができます。たとえば、作成した Orb に executors や jobs が必要ない場合は、これらのディレクトリを削除できます。

@orb.yml

@orb.yml は Orb プロジェクトの “root” に相当し、設定ファイルのバージョン、Orb の説明、display キーが記述されており、必要に応じて追加の Orb をインポートできます。

display キーは、home_url (プロダクトやサービスのホーム) と source_url (Git リポジトリの URL) に Orb レジストリへのクリック可能なリンクを追加するために使用します。

version: 2.1

description: >
  サンプルの Orb の説明

display:
  home_url: "https://www.website.com/docs"
  source_url: "https://www.github.com/EXAMPLE_ORG/EXAMPLE_PROJECT"

コマンド

再利用可能なコマンドを自分で作成して、src/commands ディレクトリに追加することができます。このディレクトリ内の各 YAML ファイルは、1 つの Orb コマンドとして扱われます。コマンド名にはファイル名が使用されます。

次の例は、単一の run ステップを含むシンプルなコマンドを示しています。このステップでは、”hello” をエコーし、値が target パラメーターで渡されます。

description: >
  # ここには、このコマンドの目的を記述します。
  # 短くわかりやすい説明を心がけます。
parameters:
  target:
    type: string
    default: "Hello"
    description: "To whom to greet?"
steps:
  - run:
      name: Hello World
      environment:
        ORB_PARAM_TARGET: << parameters.target >>
      command: echo "Hello ${ORB_PARAM_TARGET}"

使用例

使用例を作成して、src/examples ディレクトリに追加します。使用例は、エンドユーザーが自分のプロジェクトの設定ファイルにそのまま使用することを目的としたものではなく、Orb 開発者が Orb レジストリでユースケースごとの例を共有し、他のユーザーが参照できるようにするための手段です。

このディレクトリ内の各 YAML ファイルは、Orb 使用例として扱われます。名前にはファイル名が使用されます。

Orb テンプレートで完全な使用例を確認できます。

Executor

パラメーター化された Executor を作成して、src/executors ディレクトリに追加します。

このディレクトリ内の各 YAML ファイルは、1 つの Orb Executor として扱われます。名前にはファイル名が使用されます。

Orb テンプレートで完全な使用例を確認できます。

ジョブ

パラメーター化されたジョブを作成して、src/jobs ディレクトリに追加します。

このディレクトリ内の各 YAML ファイルは、Orb ジョブとして扱われます。名前にはファイル名が使用されます。

ジョブには、ユーザーが最小限の設定でタスクを完全に自動化できるように、Orb コマンドやステップを組み込むことができます。

以下は、 Orb テンプレートに含まれている hello.yml ジョブの例です。

description: >
  # ここには、このジョブの目的を記述します。
  # 短くわかりやすい説明を心がけます。

docker:
  - image: cimg/base:current
    auth:
      username: mydockerhub-user
      password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
parameters:
  greeting:
    type: string
    default: "Hello"
    description: "Select a proper greeting"
steps:
  - greet:
      greeting: "<< parameters.greeting >>"

スクリプト

Orb 開発キットの大きな利点の一つは、スクリプトのインクルード機能です。 CLI で circleci orb pack コマンドを使用すると (Orb 開発キットを使用する場合は自動化されます)、Orb 設定ファイルコード内で任意のキーに <<include(file)>> という値を使用できます。この値を使用すると、指定したファイルの内容が Orb にそのまま組み込まれます。

これは、bash コードが多数含まれるような、複雑な Orb コマンドを記述する際に特に便利です (もちろん、Python を使用することもできます!)。

スクリプトをインクルードする理由

CircleCI の設定ファイルは YAML 形式で記述されています。 bash などの論理的なコードは、カプセル化して、YAML を介して CircleCI 上で実行できますが、開発者にとっては実行形式ではないファイル内にプログラムコードを記述してテストするのは不便です。また、<<parameter>> 構文は CircleCI ネイティブの YAML 機能強化であり、ローカルで解釈、実行されるものではないため、複雑なスクリプトではパラメーターの扱いが煩雑になることがあります。

Orb 開発キットと <<include(file)>> 構文を使用すると、既存のスクリプトを Orb にインポートして、Orb スクリプトをローカルで実行、テストでき、コードに対して本格的なテストフレームワークを利用することも可能になります。

スクリプトでのパラメーターの使用

スクリプトの移植性やローカルでの実行可能性を維持するために、スクリプト内で使用する環境変数を事前に検討し、設定ファイルレベルで設定することをお勧めします。前述の greet.yml コマンドファイルに特別な <<include(file)>> 構文でインクルードされた greet.sh ファイルは、次のようなものです。

echo Hello "${PARAM_TO}"

これで、スクリプトをローカルでモックしてテストできます。

Orb のテスト

すべてのソフトウェアと同様に、品質の高い更新を確実に行うためには変更をテストする必要があります。 Orb のテストには、簡単な検証から単体テストやインテグレーションテストまで様々な方法とツールがあります。

Orb 開発キットにより作成された.circleci/ ディレクトリには、config.yml ファイルと test-deploy.yml ファイルが入っています。 config.yml ファイルには、リント、シェルチェク、レビュー、検証、そしてケースによっては、単体テストなどの Orb に用いる様々な静的なテスト方法が含まれています。一方、test-deploy.yml 設定ファイルは、Orb の開発版のインテグレーションテストのために使用されます。

詳しくは、「 Orb のテスト手法」をお読みください。

Orb のパブリッシュ

Orb 開発キットを使用すると、完全に自動化された CI/CD パイプラインが .circleci/config.yml 内に自動的に設定されます。この設定により、Orb のセマンティックバージョニングによるリリースを簡単に自動デプロイできます。

詳細については、「 Orb のパブリッシュ」を参照してください。

Orb の一覧表示

CLI を使用して、公開されている Orb を一覧表示できます。

パブリック Orb を一覧表示する場合:

circleci orb list <my-namespace>

プライベート Orb を一覧表示する場合:

circleci orb list <my-namespace> --private

circleci orb コマンドの使用方法の詳細については、 CLI に関するドキュメントを参照してください。

Orb のカテゴリ設定

Orb のカテゴリ設定は CircleCI Server では利用できません。

作成した Orb を Orb レジストリで見つけやすくするために、カテゴリを設定できます。カテゴリを設定した Orb は、 Orb レジストリでカテゴリを指定して検索できるようになります。 Orb を見つけやすくするために、CircleCI が Orb のカテゴリ項目を作成、編集する場合もあります。

カテゴリの一覧表示

CLI を使ったカテゴリリストの表示例

Orb には最大 2 つのカテゴリを選択できます。使用できるカテゴリは以下のとおりです。

Artifacts/Registry (アーティファクト/レジストリ)
Build (ビルド)
Cloud Platform (クラウドプラットフォーム)
Code Analysis (コード解析)
Collaboration (コラボレーション)
Containers (コンテナ)
Deployment (デプロイメント)
Infra Automation (インフラ自動化)
Kubernetes
Language/Framework (言語/フレームワーク)
Monitoring (モニタリング)
Notifications (通知)
Reporting (レポート)
Security (セキュリティ)
Testing (テスト)

カテゴリの一覧は、CLI コマンド circleci orb list-categories を実行して表示することもできます。このコマンドの詳細については、こちらを参照してください。

カテゴリへの Orb の追加

Orb カテゴリの追加

選んだカテゴリに Orb を追加するには、circleci orb add-to-category <namespace>/<orb> "<category-name>" を実行します。このコマンドの詳細については、こちらを参照してください。

カテゴリからの Orb の削除

カテゴリから Orb を削除するには、circleci orb remove-from-category <namespace>/<orb> "<category-name>" を実行します。このコマンドの詳細については、こちらを参照してください。

Orb のカテゴリ項目の表示

Orb に追加されたカテゴリ項目の表示

Orb に適用したカテゴリ項目を表示するには、circleci orb info <namespace>/<orb> を実行して表示される一覧を確認します。このコマンドの詳細については、こちらを参照してください。

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site