CircleCI Orb の作成

1+ year ago1 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

このチュートリアルでは、Orb 開発キットを使用して新しい Orb を作成する方法について説明します。 最初に行うのは、 GitHub.com でのリポジトリの新規作成です。

このチュートリアルの内容は次のとおりです。

  • Orb 用の GitHub リポジトリを作成する

  • Orb の設定ファイルテンプレートをニーズに応じてカスタマイズし、追加する

  • Orb 開発用の CI/CD パイプラインをセットアップし、Orb の開発に参加できるユーザーを制限する

チュートリアルを最後まで進めれば、独自の Orb を開発する準備は完了です。

本ページの手順は、以下の動画でも説明しています。

CircleCI Orb の作成と初期化

前提条件

  • CircleCI アカウントに GitHub アカウントを連携する: 手順については、「 CircleCI のユーザー登録」を参照してください。

  • ローカルマシンに CircleCI CLI をインストールして、 パーソナルアクセストークンを設定する: 必ず最新バージョンの CircleCI CLI を使用してください。 CLI のバージョンは v0.1.17087 以降である必要があります。

    $ circleci update
    
    $ circleci version
  • GitHub の組織 (Organization) 用の 名前空間を登録する: GitHub 上の組織が、Orb の作成先となる CircleCI 名前空間のオーナーとなります (個人用の組織と名前空間を使用している場合は、自動で適切に設定されます)。

Orb を作成する

2. Orb を初期化する

ターミナルを開き、以下に示す CLI の orb init コマンドを使用して新しい Orb プロジェクトを初期化します。 circleci orb init コマンドには、Orb プロジェクトを作成および初期化するためのディレクトリを指定します。

New GitHub Repo

完了すると、GitHub の URL が表示されます。 手順 4 で必要になるので、メモしておいてください。 URL は SSH か HTTPS を選択できます。どちらでも認証は可能です。

Orb Registry

3. Orb の全自動セットアップオプションを選択する

ターミナルを開き、以下に示す CLI の orb init コマンドを使用して新しい Orb プロジェクトを初期化します。 circleci orb init コマンドには、Orb プロジェクトを作成および初期化するためのディレクトリを指定します。 このディレクトリと GitHub のプロジェクトリポジトリには、同じ名前を使用することをお勧めします。

  • パブリック Orb を初期化する場合:

    circleci orb init </path/to/myProject-orb>
  • プライベート Orb を初期化する場合:

    circleci orb init </path/to/myProject-orb> --private

4. 画面の指示に従って Orb のセットアップを完了する

? Would you like to perform an automated setup of this orb?:
   ▸  Yes, walk me through the process.
      No, I will handle everything myself.

Orb のテンプレートには、Orb の パッケージ化 テスト パブリッシュを自動で行う CI/CD パイプラインが含まれています (詳細は「 Orb のパブリッシュ」を参照)。 Orb のプロジェクトが CircleCI でフォローされ、自動化済みの CI/CD パイプラインが追加されます。

セットアッププロセスでは、[パーソナル API トークン](/docs/managing-api-tokens/)を orb-publishing [コンテキスト](/docs/contexts/)に格納するかどうかを尋ねられます。

5. Orb のジョブをトリガーできるユーザーを制限する

セキュリティ グループを使用すると、ジョブのトリガーを許可したユーザーだけにアクセスを制限できます。 プライベートの パーソナル API トークンへのアクセスも、これらのユーザーだけに制限されます。 このプロセスでは、手順 1 で取得したリモート GitHub リポジトリの URL の入力も求められます。

CircleCI Web アプリで [Organization Settings (組織の設定)] > [Contexts (コンテキスト)] の順に移動して、 コンテキストを確認します。

セットアッププロセスでは、 パーソナル API トークンorb-publishing コンテキストに保存するかどうかを尋ねられます。 Orb の開発版と安定版をパブリッシュするためには、このトークンを保存しておくことが必要です。 これまでに Orb を作成したことがある場合は、コンテキストが既に存在するためこの手順はスキップできます。

6. GitHub に変更内容をプッシュする

Orb のセットアッププロセスでは、orb init コマンドにより、Orb 自動開発パイプラインの準備が整えられます。 CLI で CircleCI 上のプロジェクトのフォローまで自動的に進めるには、CLI で生成されたカスタマイズ済みの Orb テンプレートをリポジトリにプッシュする必要があります。

これを実行するよう要求されたら、別のターミナルから以下のコマンドを実行します。「default-branch」は、実際のデフォルトブランチの名前に置き換えてください。 Orb の作成が完了していれば、orb-publishing という新しいコンテキストが表示されます。 この orb-publishing をクリックして、セキュリティ グループを追加します。

コンテキストの保護

7. セットアップを完了する

変更がプッシュされたら、ターミナルに戻り、セットアッププロセスを続けます。 CLI により、CircleCI 上で Orb プロジェクトが自動的にフォローされ、サンプルコードで Orb をビルドしテストするパイプラインがトリガーされます。

CircleCI でビルド中のプロジェクトへのリンクが表示され、パイプライン全体を見ることができます。

git push origin <default-branch>

完了したら、元のターミナルに戻って、変更がプッシュされたことを確認します。

8. ダイナミックコンフィグを有効にする

Orb 開発キットでは ダイナミックコンフィグを利用しているため、この機能を有効にする必要があります。 最初のパイプラインでは、この機能が有効になっていないことを知らせるエラーメッセージが表示されます。

CircleCI のダイナミックコンフィグの入門ガイドに示されているように、CircleCI で Orb の [Project Settings (プロジェクト設定)] ページを開き、[Advanced (詳細設定)] タブにある [Enable dynamic config using setup workflows (セットアップワークフローによるダイナミックコンフィグを有効にする)] をオンにします。 また、CLI によって新しい開発ブランチ alpha に自動的に移行されたことも確認できます。 ブランチの名前は自由であり、alpha ブランチ以外で Orb の作成を進めてもかまいません。

9. 独自の Orb を作成する

デフォルト以外のブランチで (セットアップ時には alpha ブランチに自動的に移動します)、サンプルの Orb コードをニーズに合わせて変更します。 変更をプッシュするたびに、Orb が自動的にビルドおよびテストされます。

また、 .circleci/test-deploy ファイルで Orb コンポーネントのテスト方法を確認し、Orb の変更内容に応じてテストを調整してください。

最初の安定版 Orb をデプロイする準備ができたら、「 Orb のパブリッシュ」で変更した Orb のデプロイに関する情報を参照してください。 この時点で、パイプラインを手動で実行できるようになります。ただし、現時点で使用しているのはサンプルコードのみであるため、実行する必要はありません。

9. 独自の Orb を作成する

デフォルト以外のブランチで (セットアップ時には alpha ブランチに自動的に移動します)、サンプルの Orb コードをニーズに合わせて変更します。 変更をプッシュするたびに、Orb が自動的にビルドおよびテストされます。 Orb の作成方法の詳細については、 Orb の作成プロセスを参照してください。

また、 .circleci/test-deploy ファイルで Orb コンポーネントのテスト方法を確認し、Orb の変更内容に応じてテストを調整してください。 Orb のテストの詳細については、「 Orb のテスト手法」を参照してください。

最初の安定版 Orb をデプロイする準備ができたら、「 Orb のパブリッシュ」で変更した Orb のデプロイに関する情報を参照してください。

Orb のビルドとテスト

次のステップ