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

Last updated
Tags Server v3.x

はじめに

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

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

Orb 開発キット

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

はじめよう

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

GitHub 上の組織 (Organization) が、Orb の作成先となるCircleCI の名前空間のオーナーになります。 組織が自分個人のもので、名前空間のオーナーが自分自身であれば、問題ありません。

--host オプションを使用してローカルリポジトリの場所を指定することで、パブリッククラウドの Orb ではなくローカルサーバーの Orb にアクセスできます。 例えば、サーバーの場所が http://circleci.somehostname.com である場合、 --host \http://cirlceci.somehostname.com を渡すと、その Orb リポジトリに対してローカルで Orb コマンドを実行できます。

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

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

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

  2. ターミナルを開き、orb init CLI コマンドを使って新しい Orb プロジェクトを初期化します。 **CircleCI Server をご使用の場合は、必ずここで --private フラグを使って Orb をプライベートな状態に設定します。
    パブリック Orb を初期化する場合:
    circleci orb init /path/to/myProject-orb --host <your-server-installation-domain>
    

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

    circleci orb init /path/to/myProject-orb --private --host <your-server-installation-domain>
    

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

    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 オーサリングプロセスで Orb をパブリッシュする方法を参照してください。

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

    含められる CI/CD パイプラインに関する詳細は、 Orb のパブリッシュプロセス を参照してください。

    または、Orb-Project-Template をダウンロードするだけの便利な方法を選ぶ場合は、「すべて手動で行う」を選択します。

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

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

    セットアッププロセスでは、パーソナル API トークンorb-publishing <a href=”/docs/ja/2.0/contexts/>コンテキスト</a>に保存するかどうかを尋ねられます。 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 を記述します。
    CLI は、自動的に CircleCI 上の新しい Orb プロジェクトに従ってテスト用の最初の開発バージョン <namespace >/<orb>@dev:alpha を生成し終了します (hello-world サンプル)。

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

    新しいブランチから、変更を行いプッシュする準備が整いました。 この時点から、コミットごとに、Orb のパッケージ化、確認、テスト (オプション) が行われ、パブリッシュできます。

    When you are ready to deploy the first major version of your orb, find information on deploying changes with semver versioning in the Orb Publishing Process guide.

Orb の記述

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

$ git branch

* alpha
  main

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

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

type name
.circleci
.github
src
.gitignore
CHANGELOG.md
LICENSE
README.md

Orb のソース

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

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

type name
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 プロジェクト テンプレートに CHANGELOG.md ファイルが含まれています。Orb のバージョン更新のたびに、このファイルも更新してください。 ファイルは、Keep a Changelog の形式を基にしています。

Orb のパブリッシュ

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

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

Orb の一覧表示

CLI を使用して、公開中の Orb を一覧表示します。

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

circleci orb list <my-namespace> --host <your-server-hostname>

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

circleci orb list <my-namespace> --private --host <your-server-hostname>

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

次のステップ

  • CircleCI Server で Orb を管理する方法に関する詳細は、Orb の管理ガイドを参照してください。


ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか?

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。