Orb のパブリッシュ

ここでは、Orb のパブリッシュ手順について説明します。

はじめに

オーサリングした Orb は、セマンティック バージョン タグを付けてパブリッシュすることで、Orb レジストリに公開できます。

Orb のパブリッシュ プロセス

Orb 開発キット

手動ではなく、Orb 開発キットを使用して Orb をパブリッシュすると、次のセクションで説明する手順に従ってセマンティック リリースを簡単に行えます。 パブリッシュ プロセスの簡単な概要については、オーサリング プロセスの開始時に circleci orb init コマンドで生成される README.md ファイルを参照してください。

新リリースの公開

以下では、Orb の新しいセマンティック リリースを公開する方法について説明します。 circleci orb init コマンドでサンプルの Orb プロジェクトを生成すると、自動的に alpha ブランチに移行されます。 このブランチは、リポジトリの非デフォルトのブランチに新機能やバグ修正、パッチなどを作成するためのものであり、名前に深い意味はありません。 コードの追加や更新を行いリリースを公開する準備が整ったら、以下の手順を行います。

  1. デフォルト ブランチに対して新しいプル リクエストを作成します。
    新しいリリースは、デフォルト ブランチへのマージ時にのみパブリッシュされます。 Orb のパッケージ化テスト、パブリッシュは、サンプルに含まれる .circleci/config.yml 設定ファイルにより自動的に行われます。 この CI パイプラインでは、デフォルトで結合テスト単体テストが有効になっています。 Orb が正常に機能するかを確認するため、少なくとも結合テストは有効にしておくことを強くお勧めします。 Orb でスクリプトを使用しない場合や、現時点では単体テストを有効にしたくない場合は、bats/run ジョブをコメントアウトしてください。

  2. すべてのテストに合格したことを確認します。
    テスト結果は、GitHub 上においてプル リクエスト内で直接確認できます。また、CircleCI.com ではパイプライン全体に対する詳細な結果を確認できます。 プル リクエストに対して GitHub Checks API から返された Orb のテスト結果レポート

  3. プル リクエストのタイトルに特別なセマンティック バージョン タグを付けます。
    コミット メッセージに目的のセマンティック バージョン リリースを指すタグを適切に設定すると、サンプルに含まれる CI 設定ファイルの orb-tools orb により、テストに合格した Orb がデフォルト ブランチに自動でパブリッシュされます。
    タグの書式は [semver:<increment>] です。ここで、<increment> は次のいずれかの値に置き換えます。

    increment の値 説明
    major リリースのバージョン番号を 1.0.0 だけ増やして公開する
    minor リリースのバージョン番号を x.1.0 だけ増やして公開する
    patch リリースのバージョン番号を x.x.1 だけ増やして公開する
    skip リリースを公開しない

    たとえば、alpha ブランチから Orb のメジャー バージョン リリースを初めて公開する場合は、プル リクエストのタイトルを [semver:major] 初回 Orb リリース のように設定します。 Orb の初回メジャー リリース - プル リクエスト

  4. “スカッシュ” マージを行います。
    スカッシュ マージを行うと、デフォルト ブランチへのマージ時にブランチが 1 つのコミットにまとめられるだけでなく、プル リクエストのタイトルがコミット メッセージとして維持されます。 プル リクエストをスカッシュ マージして semver タイトルを保持する

  5. お疲れさまでした。
    CircleCI アプリケーションにアクセスすると、Orb のパブリッシュ パイプラインの進捗状況を確認できます。 このパイプラインが完了したら、Orb レジストリ に Orb が公開されます。

Orb のパブリッシュ プロセス

ここでは、Orb 開発キットについて掘り下げ、Orb のパブリッシュに関係するコンポーネントについて説明します。

circleci orb init コマンドは、Orb 開発パイプラインに最適な CircleCI 製設定ファイルなどを含む Orb テンプレート リポジトリを、Orb 用にクローンします。

この中の /.circleci ディレクトリに、サンプル ワークフローの詳細を示した README が含まれています。

Orb パイプラインには次の 2 つのワークフローがあります。

test-pack

2 つのワークフローのうち、実行順が先であるのは test-pack です。このワークフローは、いずれかのブランチのリポジトリにコードがコミットされるたびに実行されます。

test-pack ワークフローでは、開発版の Orb のパブリッシュ前に行うすべてのテストを実行します。 結合テスト (次のワークフローで実施) は、開発版の Orb がパブリッシュされテストを実行可能になるまで実行できません。

orb-tools/publish-dev ジョブで開発版の Orb を作成するので、このジョブを実行するために、制限付きコンテキストで保護されているパーソナル アクセス トークンへのアクセス権が必要になります。 ここで制限付きコンテキストを使用する理由は、トークンを環境変数として保存することで、ジョブをトリガー可能なユーザーをこのコンテキストにアクセス可能な人だけに制限し、パブリッシュ ステージを “保護” するためです。

このワークフローの実行内容は以下のとおりです。

  • パーソナル アクセス トークンへの特別なアクセス権が不要なテストが実行されます。このステージは、オープン ソースのプル リクエストから実行可能です。
  • ワークフローが保留状態になり、手動での承認を求められます。 開発版 Orb のパブリッシュを手動で承認する CircleCI アプリケーションにアラート プロンプトが表示され、ボタンをクリックするまでワークフローは保留状態になります。
  • 手動承認によって認証が行われると、以降のジョブも自動的に認証され、制限付きコンテキストへのアクセス権が付与されます。 このようにすることで、オープンソースのプル リクエストによる Orb に対するビルドを可能にしながら、悪意のあるコードを防止しています。
  • ワークフローが承認されると、orb-tools/publish-dev ジョブにより、開発版の Orb が次のように 2 回パブリッシュされます。

    パブリッシュされる開発タグ 説明
    <namespace>/<orb>@dev:<branch> ブランチ名にリンクされる開発タグです。 設定ファイルのテストを行う場合に使用します。
    <namespace>/<orb>@dev:${CIRCLE_SHA1:0:7} この SHA に固有の開発タグです。 次のワークフローで使用します。

テスト ジョブの詳細については、「Orb のテスト手法」を参照してください。

integration-test_deploy

CircleCI 製の Orb 開発パイプラインで実行されるワークフローは、次の integration-test_deploy で最後です。 このワークフローは、test-pack ワークフローの完了時に API から自動的にトリガーされます。 このワークフローには、test-pack ワークフローで独自に生成された開発版の Orb へのアクセス権が付与されています。

このパイプラインの第 2 ステージでは結合テストを実行し、開発版に追加およびパブリッシュされた新しい Orb の動作を確認します。

結合テストが完了すると、デフォルト ブランチでのみデプロイ ジョブが実行されます。 orb-tools/dev-promote-prod-from-commit-subject により、SHA 固有の開発版の Orb が取得され、セマンティック バージョン付きの公開バージョンにプロモートされます。


- orb-tools/dev-promote-prod-from-commit-subject: orb-name: / context: add-pr-comment: false fail-if-semver-not-indicated: true publish-version-tag: false requires: - integration-test-1 filters: branches: only:

デフォルトでは、fail-if-semver-not-indicated パラメーターは true に設定されており、タイトルに適切なセマンティック バージョン タグが含まれないコミットのビルドはすべて失敗します。

追加機能として、GitHub にバージョン タグをパブリッシュし、コメントからプル リクエストに新しいバージョンを自動で反映することなども可能です。

GitHub へのバージョン タグのパブリッシュ

パブリッシュした CircleCI Orb は、Orb レジストリでホストおよび公開されます。ただし、GitHub 上でリリースを追跡する必要がある場合は、CircleCI からバージョン タグを自動的にパブリッシュできます。

CircleCI から GitHub にタグをプッシュするには、書き込みアクセス権のあるデプロイ キーが必要です。 リンク先の記事を参照して、デプロイ キーを生成し追加してください。 追加が完了すると、そのキー用に生成された、"SO:ME:FIN:G:ER:PR:IN:T" のような “フィンガープリント” が表示されます。 この SSH フィンガープリントを、orb-tools/dev-promote-prod-from-commit-subject ジョブの ssh-fingerprints パラメーターに追加します。


- orb-tools/dev-promote-prod-from-commit-subject: publish-version-tag: true ssh-fingerprints: “SO:ME:FIN:G:ER:PR:IN:T”

利用可能なコマンド、ジョブ、パラメーターの一覧については、Orb レジストリorb-tools orb を参照してください。