Orb のベスト プラクティス

Orb のオーサリングに関するベスト プラクティスと戦略についてまとめます。 CircleCI の Orb とは、ジョブ、コマンド、Executor などの構成要素をまとめた共有可能なパッケージです。

ガイドライン

メタデータ

  • すべてのコマンド、ジョブ、Executor、パラメーターに詳細な説明文を付記します。
  • 説明文にコード リポジトリへのリンクを挿入します。
  • 説明文に Web サイトへのリンクを挿入します。
  • 説明文に API キーの取得などの前提条件を明記します。
  • Orb 要素には、一貫性がある簡潔な名前を付けます。 たとえば、単語をつなぐのにアンダーバーとハイフンを混在させないでください。

  • 少なくとも 1 つの使用例を示します。
  • 例の中で Orb のバージョンは x.y と表記します (パッチ バージョンは省略可能)。
  • 例には、ジョブが含まれない場合に最上位のジョブや他の基本的な要素を呼び出す、最も汎用的でシンプルなユースケースを使用します。
  • 必要な場合には、Orb のジョブと共に事前・事後ステップの使用方法も紹介します。

コマンド

  • 一般に、すべての Orb には少なくとも 1 つのコマンドが必要です。
  • 例外として、Executor を提供することのみを目的にした Orb を作成する場合があります。
  • 1 つ以上のパラメーター化可能ステップを組み合わせて、タスクを簡略化します。
  • ユーザーは 1 つのタスクを完了するコマンドのみを使用できます。 単独では実行できない、他のコマンドの一部として実行することのみを目的としたコマンドは作成しないでください。
  • すべての CLI コマンドを Orb コマンドに変換する必要はありません。 また、パラメーターを持たない 1 行のコマンドに必ずしも Orb コマンド エイリアスを指定する必要はありません。
  • Orb で指定された Executor 以外でコマンドを実行する場合は特に、コマンドの説明文に依存関係や前提条件を明記する必要があります。
  • コマンドに必要なパラメーター、環境変数などの依存関係がないかどうかチェックすることをお勧めします。

以下に例を示します。

if [ -z "$<<parameters.SECRET_API_KEY>>" ]; then
  echo "Error: The parameter SECRET_API_KEY is empty. Please ensure the environment variable <<parameters.SECRET_API_KEY>> has been added."
  exit 1
fi

パラメーター

  • ユーザー入力が必要な場合を除き、パラメーターには可能な限りデフォルト値を使用します。
  • env_var_name パラメーター型を使用して、API キー、Web フック URL などの機密情報を保護します。
  • ステップをパラメーターとして挿入すると、Orb で定義されたステップの間にユーザー定義のステップをジョブ内で実行できるので便利です。たとえば、コマンド内のキャッシュ ロジックの間にユーザーが提供したステップを実行するなど、ユーザー定義のタスクの前後にアクションを実行する必要がある場合に使用できます。

バイナリとツールのインストール

  • install-path パラメーターを設定し (/usr/local/bin のデフォルト値が理想的)、このパラメーター化された場所にバイナリをインストールします。 これにより、ユーザーが root 権限を持たない環境において root 権限が要求される問題を回避できる可能性が高くなります。
  • root が必要なユースケースでは、事前チェックを追加して、ユーザーが root 権限を持っているかどうかを確認し、ユーザーに適切な権限が必要な場合にはその旨を明確なエラー メッセージでユーザーに警告します。
  • $BASH_ENV を介してユーザーのパスにバイナリを追加すると、ユーザーは別の run ステートメントからバイナリを呼び出せるようになります。 デフォルト以外のパスにインストールするときにはこの方法で実行する必要があります。 以下に例を示します。
    echo `export PATH="$PATH:<<parameters.install-path>>"` >> $BASH_ENV
    

ジョブ

  • ジョブは、Orb 内で定義されたコマンドを使用して、その Orb の一般的なユース ケースをオーケストレーションする必要があります。
  • 柔軟性を考慮します。
  • ユーザーが事後ステップ、事前ステップ、パラメーターとしてのステップをどのように利用できるかを考慮します。
  • パススルー パラメーターの作成を検討します。
  • パラメーターを受け入れる Executor またはコマンドを使用するジョブで、Executor またはコマンドにパラメーターを渡すには、ジョブにもそれらのパラメーターが必要です。
  • Executor をハードコーディングしてはなりません。 イメージまたはタグを上書きできるパラメーター化可能な Executor を使用します (‘default’ など)。

Executor

  • サポートされている OS (MacOs、Windows、Docker、VM) ごとに少なくとも 1 つの Executor が必要です。
  • デフォルトの Executor を含める必要があります。
  • 含まれているイメージに問題が発生した場合に、ユーザーがバージョンやタグを上書きできるよう、Executor をパラメーター化する必要があります。

インポートする Orb

  • 変更不可の完全なセマンティック バージョンの Orb をインポートする必要があります。 こうすることで、ロック ファイルなど、依存関係のある Orb への変更による影響から Orb を保護できます。
  • [パートナーのみ] - 承認済みおよびパートナーの名前空間、または同じ名前空間の Orb のみをインポートする必要があります。

保全性

  • Orb スターター キット (ベータ版) を使用して、完全に自動化されたビルド > テスト > デプロイのワークフローで Orb の CI/CD をデプロイします。 これで、以降のすべてが処理されます。
  • オプション: Orb をパターンに分解して使用すると、個別の Orb コンポーネントのメンテナンスがさらに簡単になります。

デプロイ

バージョニング

  • セマンティック バージョニング (x.y.z) を使用します。
  • メジャー: 互換性がない変更
  • マイナー: 下位互換性を維持した新機能の追加
  • パッチ: 小さなバグの修正やメタデータの更新などの安全なアクション

Orb のデプロイに関するベスト プラクティス ガイドを参照してください (近日追加予定)。

このセクションは、Orb スターター キットによって自動的に処理されます。

GitHub および Bitbucket

GitHub では、”topics” でリポジトリにタグ付けできます。 トピックは GitHub 検索でデータポイントとして使用されます。さらに、GitHub の [Explore] ページでは、このタグを使用してリポジトリがグループ化されます。 Orb を格納するリポジトリには、circleci-orbs のトピックを使用することをお勧めします。 CircleCI Orb、パートナー Orb、コミュニティ Orb のどれであっても、このトピックを使用することで、Orb レポジトリがこちらのページに掲載されます。

トピックでリポジトリを分類する