CircleCI Orb の作成

1+ year ago1 min read

クラウド

Server v4.x

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 を作成する

作成した Orb を削除することはできません。また、Orb はセマンティックバージョニングに準拠しており、パブリッシュ後に変更を加えることもできません。パブリッシュされた Orb は別のプロジェクトで必須とされる可能性があります。そのため、いずれかのプロジェクトが突然機能しなくなる事態を防ぐために、Orb の削除は禁止されています。

2. Orb を初期化する

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

CircleCI Server をご利用の場合は、Orb をプライベートのインストール環境に保持するために、--private フラグを使用してください。 "README.md を追加する"、"ライセンスを選ぶ" といったオプションのチェックはすべて外してください。

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

この段階で Orb リポジトリをプルする必要はありません。プルは、次の手順で orb init を実行する際に行います。このコマンドの前にリポジトリをプルすると、問題が発生します。

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

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

CircleCI Server をご利用の場合は、Orb をプライベートのインストール環境に保持するために、--private フラグを使用してください。

一旦初期化した Orb をパブリックからプライベート、またはその逆に変えることはできません。プライベート Orb を作成する場合は、必ず --private フラグを指定してください。

パブリック 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/)に格納するかどうかを尋ねられます。

Orb のテンプレートをダウンロードするだけに留める場合は、「No, I will handle everything myself (いいえ。すべて手動で行う)」を選択します。手動オプションを選択した場合は、「 Orb の手動作成プロセス」に従って Orb の作成とパブリッシュを行ってください。

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 のビルドとテスト

次のステップ

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site