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

Last updated
Tags クラウド Server v3.x

全般

Give your orb a descriptive name

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

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

Categorize your orb

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

Ensure all orb components include descriptions

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

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

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

Ensure your orb-publishing context is restricted

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

構成

@orb.yml

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

All orbs should include a description

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"

コマンド

Most orbs will contain at least one command

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

Use the minimal number of steps required.

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

Check for root

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

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

$SUDO do_command

ジョブ

Consider “pass-through” parameters

ジョブ内でコマンドまたは 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 のバージョンを選択します。 Uses CircleCI's highly cached convenience
  images built for CI.

  CI 向けにキャッシュを活用して開発された
  CircleCI 製コンビニエンス イメージを使用します。

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

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

A docker image parameter might be preferable to an executor

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

Consider post and pre steps, and step parameters

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

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

Executor

Orbs do not always require an executor

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

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

使用例を付ける

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

Be sure to name your usage examples so they reflect the use-case they demonstrate.

Good Usage Example Names Bad Usage Example Names
deploy-to-service
install-cli demo

All public orbs should contain at least one usage example.

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

Use-case based examples

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

Show correct orb version

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

パラメーター

Secrets should never be directly entered

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

Parameterize the installation path

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

デプロイメント

Always follow strict semantic versioning

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

Keep a changelog

Keeping a concise changelog allows users of an orb to quickly see what has changed in a particular version. While git does provide a log of changes, it can be difficult to discover the difference between two versions, especially when commits don’t neccesarily align to a release. Changelogs should conform to the Keep a Changelog guidelines.

宣伝

Share your orb with the community!

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



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

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

サポートが必要ですか?

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

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