Orb のオーサリング プロセス

はじめに

この Orb オーサリング ガイドは、事前に「Orb の概要」を読み、名前空間の作成が完了していることを前提としています。 完了している場合、Orb の開発をすすめることができます。

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

Orb 開発キット

Orb 開発キットは、相互に連携する複数のツールをセットにしたものです。キットを使うと CircleCI でのテストとデプロイが自動化されるため、Orb の開発プロセスが容易になります。 Orb 開発キットは、次の要素で構成されています。

作業を開始する

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

GitHub 上の組織 (Organization) が、Orb の名前空間の所有者であることを確認ください。これがあなた自身の個人的な組織であり、名前空間であれば、問題ありません。

  1. 新しい GitHub リポジトリを作成します。
    リポジトリの名前は、特に重要な役割はありませんが、”myProject-orb” のようなわかりやすい名前を付けることをお勧めします。 Orb レジストリ

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

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

パブリック Orb を初期化する場合:

circleci orb init /path/to/myProject-orb

プライベート Orb を初期化する場合:

circleci orb init /path/to/myProject-orb --private

circleci orb init コマンドを、Orb プロジェクトを作成・初期化するためのディレクトリを指定して実行します。 このディレクトリと Git のプロジェクト リポジトリには、同じ名前を使用することをお勧めします。

  1. Orb の完全自動セットアップ オプションを選択します。
    ? Would you like to perform an automated setup of this orb?:
      ▸ Yes, walk me through the process.
     No, I'll handle everything myself.
    

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

    含められる CI/CD パイプラインの詳細については、「Orb のパブリッシュ」を参照してください。 または、Orb プロジェクト テンプレートをダウンロードするだけに留める場合は、「No, I’ll handle everything myself (すべて手動で行う)」を選択します。

  2. 質問に答えて Orb の構成とセットアップを進めます。
    バックグラウンドでは、orb init コマンドが Orb プロジェクト テンプレートをコピーし、回答に基づいてカスタマイズを実行します。 各ディレクトリにある詳細な README.md ファイルには、それぞれのディレクトリのコンテンツに関する有益な情報が記載されています。 手順 1 でメモしておいたリモート Git リポジトリの URL も、ここで入力を求められます。

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

    セットアップ プロセスでは、パーソナル API トークンorb-publishing コンテキストに格納するかどうかを尋ねられます。 Orb の開発版と安定版をパブリッシュするために、このトークンを格納しておくことが必要になります。

    コンテキストは必ず使用者を制限する
    [Organization Settings (組織設定)] > [Contexts (コンテキスト)] に移動して、コンテキストを制限してください。

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

    詳細については、「コンテキストの使用」を参照してください。

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

    完了したら、元のターミナルに戻って、変更がプッシュされたことを確認します。

  4. Orb の記述を完了します。
    新しい Orb プロジェクトが CircleCI で自動的にフォローされ、テスト用に最初の開発バージョン <namespace>/<orb>@dev:alpha (hello-world サンプル) が生成されて、CLI が終了します。

    CircleCI 上にビルドされたプロジェクトへのリンクが提供されます。そこで、バリデーション、パッケージ化、テスト、パブリッシュのプロセスを確認できます。 また、CLI によって自動的に alpha という新しい開発ブランチに移行したことも確認できます。

    この新しいブランチから、変更を加えたりプッシュしたりすることができます。 これで、コミットするたびに、Orb がパッケージ化、バリデーション、テスト (任意) され、パブリッシュできるようになりました。

    Orb の最初のメジャー バージョンをデプロイする準備が整ったら、「Orb のパブリッシュ」で、セマンティック バージョニング (semver) を使った変更のデプロイに関する情報を確認してください。

Orb の記述

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

$ git branch

* alpha
  main

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

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

種類 名前
.circleci
.github
src
.gitignore
CHANGELOG.md
LICENSE
README.md

Orb のソース

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

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

種類 名前
commands
examples
executors
jobs
@orb.yml

上記のディレクトリは、作成した Orb に含まれる Orb コンポーネントを表しています。Orb によっては、一部のコンポーネントが含まれない場合もあります。 @orb.yml は Orb のルートの役割を果たします。 任意で Orb 開発を強化するための scripts ディレクトリと tests ディレクトリがプロジェクトに含まれている場合もあります。これらのディレクトリについては、このページの「スクリプト」セクションと、「Orb のテスト手法」に解説があります。

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

@orb.yml

@orb.yml は Orb プロジェクトの “ルート” に相当し、設定ファイルのバージョン、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"
Commands

再利用可能なコマンドを作成し、src/commands ディレクトリに追加します。 このディレクトリ内の各 YAML ファイルは、ファイル名と一致する名前のorbコマンドとして扱われます。

以下は、Orb プロジェクト テンプレートに含まれているサンプル コマンドの greet.yml です。

description: >
  # ここには、このコマンドの目的を記述します。
  # 短くわかりやすい説明を心がけます。
parameters:
  greeting:
    type: string
    default: "Hello"
    description: "適切なあいさつの選択"
steps:
  - run:
      name: あいさつを選択して Hello World を実行
      command: echo << parameters.greeting >> world
Examples

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

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

Orb プロジェクト テンプレートでサンプルを確認できます。

Executors

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

このディレクトリ内の各 YAML ファイルは、ファイル名と一致する名前の Orb Executorとして扱われます。

Orb プロジェクト テンプレートでサンプルを確認できます。

Jobs

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

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

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

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

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

docker:
  - image: cimg/base:stable
parameters:
  greeting:
    type: string
    default: "Hello"
    description: "適切なあいさつの選択"
steps:
  - greet:
      greeting: "<< parameters.greeting >>"

スクリプト

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

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

parameters:
  to:
    type: string
    default: "World"
    description: "あいさつする相手"
steps:
  - run:
      environment:
        PARAM_TO: <<parameters.to>>
      name: greet ファイルで指定した相手にあいさつ
      command: <<include(scripts/greet.sh)>>
parameters:
  to:
    type: string
    default: "World"
    description: "あいさつする相手"
steps:
  - run:
      name: 指定した相手にあいさつ
      command: echo "Hello <<parameters.to>>"
スクリプトをインクルードする理由

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

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

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

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

echo Hello "${PARAM_TO}"

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

Orb のテスト

他のソフトウェアと同様、コードをテストする方法は複数あります。どれだけのテストを実装するかは、開発者が決めることができます。 この時点で、設定ファイル内には integration-test-1 という名前のジョブがあります。作成した Orb コンポーネントをテストするには、このジョブを更新する必要があります。 これは一種の結合テストで、 Orb の単体テストも可能です。

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

更新履歴の記録

Orb のバージョン間の違いは、ときに判別しにくいものです。 そのため、セマンティック バージョニングと合わせて、バージョン間の変更内容をわかりやすく示した更新履歴の提供もお勧めします。 Orb プロジェクト テンプレートに CHANGELOG.md ファイルが含まれています。Orb のバージョン更新のたびに、このファイルも更新してください。 ファイルは、Keep a Changelog の形式を基にしています。

Orb のパブリッシュ

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

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

Orb のカテゴリ設定

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

カテゴリの一覧表示

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 を追加するには、circleci orb add-to-category <namespace>/<orb> "<category-name>" を実行します。 このコマンドの詳細については、こちらを参照してください。

カテゴリからの Orb の削除

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

Orb のカテゴリ項目の表示

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

Orb の一覧表示

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

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

circleci orb list <my-namespace>

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

circleci orb list <my-namespace> --private

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