ドキュメント
circleci.com
Start Building for Free

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

2 weeks ago1 min read
クラウド
Server v3.x
On This Page

全般

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

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

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

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 の用途や機能がわかりやすくなるだけでなく、検索で見つけてもらえる可能性も上がります。

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 が “ノイズ” 過多にならないよう、使用するステップの数はできるだけ少なくしてください。

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

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

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

$SUDO do_command

ジョブ

パラメーターを “パススルー” する

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

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

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

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

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

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

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

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

Executor

Orb には必ずしも Executor が必要ではない

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

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

使用例を付ける

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

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

良い使用例の名前悪い使用例の名前
deploy-to-serviceexample
install-clidemo

すべてのパブリック Orb には使用例を 1 つ以上含める

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

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

各使用例には、タスクの実行方法を紹介するユースケースに応じた名前を付けてください。 たとえば、install_cli_and_deployscan_docker_containertest_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 ユーザーは特定のバージョンで何か変わったのかを素早く確認できます。 Git では変更の履歴が提供されていますが、特にコミットがリリースと常に一致していない場合、 2 つのバージョンの違いを見つけるのは困難です。 更新履歴は、 更新履歴の記録 に基づいて作成してください。

宣伝

オーサリングした Orb をコミュニティで宣伝する

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


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

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

サポートが必要ですか

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

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