Orb のオーサリングのベストプラクティス

全般
構成
デプロイメント
宣伝

全般

Orb にわかりやすい名前を付ける

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

適切な Orb スラッグ	不適切な Orb スラッグ
circleci/node	circleci/node-orb
company/orb	company/company

Orb にカテゴリを設定する

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

Orb のすべてのコンポーネントに説明を付ける

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

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

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

Orb のパブリッシュのコンテキストは制限付きにする

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

構成

@orb.yml

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

すべての Orb に説明を含める

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

display リンクを設定する

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 つ以上含める

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

使用するステップの数は必要最低限に抑える

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

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

description: "不適切なデプロイ コマンドの例。 可能であればステップには名前を付け、まとめるようにしてください。"
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

root ユーザーかどうかを確認する

コマンドに “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"。リリースの全一覧は
      次を参照してください: https://nodejs.org/en/download/releases
    type: string
executor:
  name: default
  tag: << parameters.version >>

description: >
  使用する Node.js のバージョンを選択します。 CI 向けにキャッシュを活用して開発された
  CircleCI 製コンビニエンス イメージを使用します。

  次のリストにあるすべてのタグを使用できます。
  https://circleci.com/developer/ja/images/image/cimg/node
docker:
  - image: 'cimg/node:<<parameters.tag>>'
parameters:
  tag:
    default: '13.11'
    description: >
      cimg/node イメージのバージョン タグを次から選択してください。
      https://circleci.com/developer/ja/images/image/cimg/node
    type: string

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

Docker イメージのパラメーターが Executor に適していないか検討する

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

事後ステップ、事前ステップ、ステップ型パラメーターを使用する

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

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

Executor

Orb には Executor を含めなくてもよい

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

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

使用例を付ける

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

すべての公開版 Orb には使用例を 1 つ以上含める

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

ユースケースに合わせた使用例を書く

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

正確な Orb のバージョンを記載する

各使用例では、インポートする 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 をコミュニティで宣伝する

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

Orb のオーサリングのベスト プラクティス

全般