Orb のパブリッシュ

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

はじめに

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

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

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

Orb 開発キット

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

新リリースの公開

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

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

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

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

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

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

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

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

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

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

Included in the /.circleci directory is a README with a breakdown of the included workflows.

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

test-pack

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

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

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

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

The workflow runs as follows:

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

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

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

integration-test_deploy

  • integration-test-1 filters: branches: only: <your default branch>

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

This second stage of the pipeline runs the integration tests, testing the new orb’s functionality that has just been added and published to the development version..

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

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

The fail-if-semver-not-indicated parameter is set to true by default, ensuring any commits without the proper semver tag in the commit title, result in a failed build.

追加機能として、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"

You can find a full set of available commands, jobs and parameters for the orb-tools orb on the Orb Registry.



Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.