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 をメモしておいてください。手順 4 で必要になります。 URL は SSH か HTTPS を選択できます。どちらを選択しても認証を行えます。 Orb レジストリ

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

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

  3. 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-Project-Template がダウンロードされ、カスタマイズした設定内容が自動的に反映されます。 プロジェクトは CircleCI でフォローされ、自動化された CI/CD パイプラインが含められます。

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

  4. 質問に答えて 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 トークンにアクセスできるのも、これらのユーザーだけです。

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

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

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

  6. 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"
コマンド

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

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

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

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

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

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

Executor

パラメーター化された Executor をオーサリングして、src/executors ディレクトリに追加できます。

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

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

ジョブ

パラメーター化されたジョブ をオーサリングして、src/jobs ディレクトリに追加できます。

このディレクトリ内の各 YAML ファイルは、1 つの 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 開発キットを使用すると、完全に自動化された 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> を実行して表示される一覧を確認します。 このコマンドの詳細については、こちらを参照してください。