Orb の作成のベストプラクティス

Orb のスラッグ “slug” は、名前空間_と _Orb 名をスラッシュで区切って指定します。 名前空間には Orb を所有し管理するユーザー、会社、または組織を指定し、Orb 名自体には、その Orb で提供するプロダクトやサービス、アクションを記述します。

Orb にカテゴリを設定すると、 Orb レジストリでカテゴリを指定して検索できるようになります。 CircleCI CLI を使用して Orb のカテゴリを設定する方法は、「 Orb の作成プロセス」の該当セクションを参照してください。

コマンド、ジョブ、Executor、使用例、パラメーターのすべてに説明を付けることができます。 Orb の各コンポーネントにわかりやすい説明を付けるとともに、必要に応じて補足のドキュメントを提供してください。

description: "このコマンドは UI のステップで Hello と出力するために使用します。 "
steps:
  - run:
      name: "echo コマンドの実行"
      command: echo "Hello"

Orb コンポーネントのメリットと使用法がよくわかる詳しい説明を記載してください。 また、説明には、各コンポーネントに関連する詳細なドキュメントへのリンクを記載することもお勧めします。

Orb 開発キットを使うと、CircleCI パーソナルアクセストークンは組織のコンテキストに保存されます。 このコンテキストにアクセスするジョブが承認済みのユーザーによりトリガーまたは承認されたとき以外に実行されないように、コンテキストを制限してください。 詳細については、「 コンテキストの使用」を参照してください。

@orb.yml ファイルはプロジェクトの “ルート” であり、Orb レジストリと CLI に表示される Orb のメタデータの大部分をここに記載します。

Orb レジストリにパブリッシュされた Orb は、名前と説明で検索可能になります。 適切な説明を付けると、ユーザーにとって Orb の用途や機能がわかりやすくなるだけでなく、検索で見つけてもらえる可能性も上がります。

Orb の特殊な設定キー display では、source_url に、Orb のソースコードが載っている Git リポジトリへのリンクを設定できます。また、home_url には、必要に応じて製品やサービスのホームページへのリンクを設定できます。

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

ほとんどの Orb には、コマンドを少なくとも 1 つ含めます。 コマンドは、ユーザーを介さずにシェル コマンドや CircleCI の特殊なステップを自動的に実行するために使用します。 例外として、ツールで特定の Docker コンテナを使用する_必要がある_場合などは、Orb にコマンドを含めずジョブだけを設定してもかまいません。

Orb 用に 再利用可能なコマンドを作成する場合、任意の数の ステップを設定することが可能です。 ステップの名前はユーザーの UI に表示されるので、各ステップには適切な名前を付けてください。 UI が “ノイズ” 過多にならないよう、使用するステップの数はできるだけ少なくしてください。

"
parameters:
  api-token:
    type: env_var_name
    default: MY_SECRET_TOKEN
steps:
  - run: pip install example
  - run: example login $<<parameters.api-token>>
  - run: example deploy my-app

description: "CLI のインストール、アプリケーションの認証とデプロイを行うデモ用コマンド。 "
parameters:
  api-token:
    type: env_var_name
    default: MY_SECRET_TOKEN
steps:
  - run:
      name: "アプリケーションのデプロイ"
      command: |
        pip install example
        example login $<<parameters.api-token>>
        example deploy my-app

コマンドに “sudo” を付ける場合、まずユーザーが既に root であるかどうかを確認してください。 この確認は、環境変数を用いることで動的に行なえます。

if [[ $EUID == 0 ]]; then export SUDO=""; else # root ユーザーかどうかを確認
  export SUDO="sudo";
fi

$SUDO do_command

ジョブ内でコマンドまたは Executor を使用する場合は、ジョブ内にこれらのコンポーネントそれぞれのパラメーターのコピーを含めてください。 こうすることで、ジョブで指定したパラメーターを、それらのパラメーターを参照する各コンポーネントに “パススルー” することが可能です。

例として、 Node Orb に含まれる test ジョブのスニペットの一部を次に示します。

description: |
  Node.js アプリケーションを自動的にテストするシンプルなドロップイン ジョブ。
parameters:
  version:
    default: 13.11.0
    description: >
      完全なバージョン タグを指定してください。
例: "13.11.0"。
parameters:
  version:
    default: 13.11.0
    description: >
      A full version tag must be specified.
parameters:
  version:
    default: 13.11.0
    description: >
      A full version tag must be specified. リリースの全一覧は
      次を参照してください: https://nodejs.org/en/download/releases
    type: string
executor:
  name: default
  tag: << parameters.version >>

description: >
  使用する Node.js のバージョンを選択します。 CI 用にビルドされ高度にキャッシュされた Circle CI イメージを使用:

  このリストのタグはすべてご使用いただけます。
  https://circleci.com/developer/images/image/cimg/node
docker:
  - image: 'cimg/node:<<parameters.tag>>'
    auth:
      username: mydockerhub-user
      password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
parameters:
  tag:
    default: '13.11'
    description: >
      Pick a specific cimg/node image version tag:
      https://circleci.com/developer/images/image/cimg/node
    type: string

上記のように、このジョブでは、version パラメーターを取る default という名前の Executor を使用しています。 Executor の version パラメーターをこの_ジョブ_のユーザーが設定できるようにするには、ジョブ内に該当するパラメーターを作成し、そのパラメーターを他の Orb コンポーネントに渡す必要があります。

Orb に特定の実行環境が必要なジョブを複数設定しているのであれば、 カスタム Executor を実装することをお勧めします。 ジョブの実行環境のほとんどが Linux プラットフォームである場合には、 ジョブ内で直接 Docker Executor を使用し、イメージをパラメーター化することを検討してください。

CircleCI のジョブでは、その実行前後にステップを挿入することができます。また、パラメーターを使用することでジョブ内にステップを挿入することも可能です。 一般的に、カスタム ジョブにコマンドを組み込む (該当する場合) よりも、ジョブを設定する方がユーザーにとっては容易です。 挿入可能なステップを用いると、ジョブの柔軟性が高まるだけでなく、Orb で新機能を試しやすくなります。

詳しくは次を参照してください。

• 事前ステップと事後ステップ
• ステップ型パラメーター

Orb の開発で、特定の実行環境でしか実行できないジョブを複数設定する場合は、Executor を使用してその環境を提供または利用することが一般的です。 たとえば、Orb で特定の Docker コンテナを利用しジョブを 2 つ含め、コマンドは含めない場合には、両方のジョブ用にこの実行環境を 1 つの 再利用可能な Executor として抽象化すると便利です。

Executor は、Orb 以外でも、特にカスタム ジョブの マトリックス テストを作成するのに役立ちます。

Orb の作成者にとって Orb の 使用例は、コミュニティにユースケースやベストプラクティスを伝える最適な手段です。 使用例は、Orb を利用するユーザーが参照する主要なドキュメントになるので、わかりやすく役立つ例を載せることが重要です。

使用例には必ず名前をつけて、使用例が示すユースケースを反映できるようにしてください。

他組織に提供する Orb には、少なくとも 1 つの使用例と説明を付けてください。

各使用例には、タスクの実行方法を紹介するユースケースに応じた名前を付けてください。 たとえば、install_cli_and_deploy、scan_docker_container、test_application_with_this-tool などです。

各使用例では、インポートする Orb の記載なども含め、完全な例を示してください。 使用例で示すバージョン番号は、パブリッシュする最新の Orb のものと一致させる必要があります。 たとえば、現在の Orb のバージョンが 0.1.0 であり、プル リクエストを作成してバージョン 1.0.0 をパブリッシュする場合は、使用例を更新し、使用する Orb のバージョン番号を 1.0.0 に変更します。

API キーや認証トークン、パスワードなど、”シークレット” に該当する情報はすべて、パラメーター値として直接入力しないようにしてください。 その代わりに、 env_var_name パラメーター型を使用して環境変数の名前を文字列値として指定し、この変数に機密情報を指定します。

未知のユーザー定義の Docker イメージにバイナリをインストールする場合、利用可能な権限を知ることは困難です。 可能であれば、install-path パラメーターを設定し (/usr/local/bin のデフォルト値が理想的)、このパスにバイナリをインストールします。 多くの場合、こうすることで、”root” 権限が認められていない環境でこの権限を要求してしまう事態を回避できます。

セマンティック バージョニングに従うと、バージョン番号からバグの修正やパッチ、新機能の追加、互換性を損なう変更のいずれが行われたかわかるので、更新やリリースではこの手法に従うことが重要です。 たとえば、互換性を損なう変更をパッチとして導入すると、Orb のユーザーに対し、CI プロセスの妨げになる更新プログラムが自動で配信されてしまう可能性があります。 Orb を更新する前に、 セマンティック バージョニングに関する記事をよく読み、この手法を身につけてください。

簡潔な更新履歴を記録することにより、Orb ユーザーは特定のバージョンで何か変わったのかを素早く確認できます。 Git では変更の履歴が提供されていますが、特にコミットがリリースと常に一致していない場合、 2 つのバージョンの違いを見つけるのは困難です。 更新履歴は、 更新履歴の記録 に基づいて作成してください。

Orb レジストリに Orb をパブリッシュした場合は、 ぜひ、 CircleCI Discuss フォーラムに紹介記事を投稿してください。