ドキュメント
無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

Orb のコンセプト

1+ year ago2 min read
このページの内容

CircleCI Orb とは、 ジョブ、 コマンド、 Executor などの、共有可能な設定要素をパッケージ化したものです。 Orb により CircleCI の設定の記述やカスタマイズが簡単に行えます。 Orb で使用されている再利用可能な設定要素については、 再利用可能な設定ファイルのリファレンスで詳しく説明されています。

Orb の設定要素

CircleCI の 再利用可能な設定ファイル機能により、パラメーター化できる設定要素の定義や、その要素をプロジェクトの設定ファイル全体で再利用することが可能です。 設定ファイルのリファレンス機能をすべて理解してから、 再利用可能な設定ファイルのリファレンスに移ることをお勧めします。

コマンド

コマンドには、 パラメーター を使って動作を変更できる1つまたは複数のステップが含まれています。 コマンドは Orb のロジックであり、 コードをチェックアウトする、シェルコードを実行する</a>などのステップを実行する役割を担っており、例えば、bash や CLI ツールを実行します。 詳細については、 再利用可能なコマンドの作成 ガイドを参照してください。

例えば、AWS S3 Orb には、ファイルやオブジェクトを新しい場所にコピーする コマンド: aws-s3/copyがあります。 AWS認証の詳細が環境変数として保存されている場合、このコマンドを設定で使用するための構文は単純です。

version: 2.1

orbs:
 aws-s3: circleci/aws-s3@x.y.z

jobs:
   build:
    docker:
      - image: 'cimg/python:3.6'
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - run: mkdir bucket && echo "lorem ipsum" > bucket/build_asset.txt
 # aws-s3 Orb の "copy" コマンドを使用
      - aws-s3/copy:
          from: bucket/build_asset.txt
          to: 's3://my-s3-bucket-name'

  #...ワークフロー、その他のジョブなど

詳細は、レジストリの AWS-S3 Orbをご覧ください。

Executor

Executor は、 ジョブ を実行することができるパラメータ化された実行環境です。 CircleCIでは複数の Executor オプションを提供しています。

  • Docker
  • macOS
  • Windows
  • Linux VM

Orb 内 で定義された Executor は、お客様のプロジェクト設定のジョブや Orb で定義されたジョブの実行に使用できます。

Executor の定義例

例えば、 Node Orb では、パラメータ化された Docker ベースの Executor が提供されており、これを介して Docker タグを設定することができます。 これは、Node Orb の テストジョブと一緒に使用することで、すべてのバージョンの Node.js に対してアプリケーションをテストする簡単な方法です。

詳しくは、 再利用可能な Executor の作成 や、 Node Orb のレジストリを参照してください。

ジョブ

ジョブ は、与えられた Executor 内で実行される一連の ステップを定義し、 ワークフローを使ってオーケストレーションされます。 また、ジョブは個別に GitHub Checks を介してステータスを返します。

ジョブがある Orb をインポートする際に、ワークフローから直接ジョブを参照することができます。

version: 2.1

orbs:
  <orb>: <namespace>/<orb>@x.y # Orb のバージョン

workflows:
  use-orb-job:
    jobs:
      - <orb>/<job-name>

詳細については、 再利用可能なジョブの作成 、および Orb レジストリにある Node テストジョブの使用例 を参照してください。

使用例

Orb 開発キットを使用して、新しい使用例を追加するには、Orb プロジェクトの src/examples ディレクトリ内に name-of-example.yml という新しいファイルを作成するだけです。 使用例は、プロジェクト設定で直接使用するものではありませんが、設定で Orb を最大限に活用する方法を共有するための Orb メタデータの一つです。 参照用に、 Orb レジストリに下記のようなサンプルが表示されます。 以下は使用例のサンプルです。

# Source https://github.com/circleci-public/Orb-Template/blob/main/src/examples/example.yml

description: >
  Sample example description.
usage:
  version: 2.1
  orbs:
    <orb-name>: <namespace>/<orb-name>@1.2.3
  workflows:
    use-my-orb:
      jobs:
        - <orb-name>/<job-name>

名前空間

名前空間 は、一連の Orb を作成者別にグループ化するために、ユーザーや組織が要求する一意の識別子です。 各ユーザーまたは組織が要求できる一意の名前空間は 1 つのみで、後から変更することはできません。 各名前空間には、一意の名前の Orb が多数含まれる場合があります。

例えば、circleci/rails という Orb と <other-namespace>/railsという Orb は、別々の名前空間にあるため、レジストリ内で共存できます。

デフォルトでは、各組織が要求できる名前空間は 1 つに制限されています。 これは、名前の占有や名前空間のノイズを制限するためのポリシーです。 名前空間の変更が必要な場合は、サポートにお問い合わせください。

デフォルトでは、作成された名前空間は、 Orb レジストリの「コミュニティ」の名前空間として表示されます。

セマンティック バージョニング

Orb は セマンティック バージョニング のリリースプロセスを採用しています。各 Orb のアップデートは標準化されたバージョニングパターンに従っており、Orb の作成者やユーザーはそれを活用してください。

セマンティックバージョニングでは、リリースバージョンは .で区切られた 3 つの整数で表されます。 それぞれの整数は、追加される変更の種類を表します。

[Major].[Minor].[Patch]
バージョン説明
メジャー大きな変更
マイナー後方互換性のある追加機能
パッチバグの修正

Orb をインポートすると、その Orb を特定のセマンティック バージョニングのコンポーネントに固定することができます。

インポートバージョン説明
1.2.3フルバージョンと一致。 変更は取り込まれません。
1.2メジャーバージョン 1、マイナーバージョン 2にロックされており、すべてのパッチアップデートを受け取ります。
1メジャーバージョン1にロックされています。 すべてのマイナーアップデートとパッチアップデートを受け取ります。 メジャーバージョンは自動的には変更されません。
volatile**推奨しません。 ** 最後にパブリッシュされたバージョンの Orb をプルするためテスト時には便利です。 セマンティック バージョニングは適用されません。

ユーザーの CI プロセスに悪影響を与えないように、Orb 作成者はセマンティック バージョン管理を厳密に行い、 マイナー または パッチ レベルの更新時に大きな変更が取り込まれないようにする必要があります。

Orb のバージョン（開発版、安定版、インライン版）

安定版 Orb

安定版の Orb は変更不可であり、 Orb レジストリで見つけることができます。

  • 安定版 Orbは、変更不可であり、削除や編集ができず、更新は新しいセマンティック バージョンのリリースで提供される必要があります。
  • バージョンの文字列は セマンティック バージョニング形式でなければなりません。 例えば、 <namespace>/<orb>@1.2.3のようになります。
  • 安定版 Orb は、名前空間の組織のオーナーのみがパブリッシュできます。
  • Orb レジストリへのパブリッシュ
  • オープンソースは MIT ライセンスでリリースされます。
  • CircleCI CLI から利用可能です。

開発版 Orb

開発版 Orb は一時的に上書きが可能な Orb タグのバージョンで、安定版用の変更をデプロイしたセマンティック バージョンをデプロイする前の迅速な開発およびテストに役立ちます。

  • 開発版 Orb は変更可能で、上書きすることができ、パブリッシュ後90日で自動的に失効します。
  • バージョンの文字列は、dev:で始まり、<namespace>/<orb>@dev:my-feature-branch のような任意の文字列が続きます。
  • 開発版 Orb は、名前空間の組織のメンバーであれば誰でもパブリッシュすることができます。
  • Orb レジストリには表示されません。
  • オープンソースは MIT ライセンスでリリースされます。
  • CircleCI CLI から利用可能です（開発タグ名が分かる場合）。

インライン Orb

インライン Orb は、ユーザーの設定内で直接定義され、完全にローカルで、個々のプロジェクトにスコープされています。

参照: インライン Orb の記述方法 を参照してください。

  • Orb サービスにはパブリッシュされません。
  • バージョニングされません。
  • ユーザーの設定内でローカルにのみ存在します。
  • リポジトリの外からはアクセスできません。
  • 非公開です。
  • CircleCI CLI からはアクセスできません。

プライベート Orb とパブリック Orb

Orb をパブリッシュする方法は 2 つあります。パブリックまたはプライベートです。

  • 組織内のメンバーだけが Orb を閲覧したり使用できるようにするには、 プライベート Orb をパブリッシュします。
  • Orb を CircleCI Orb レジストリにパブリッシュし誰でも使用できるようにするには、パブリック Orb を作成します。

プライベート Orb について下記で詳しく説明します。

プライベート Orb

CircleCI のすべての プランでプライベート Orb を無制限にご利用いただけます。 プライベート Orb 機能と使うと、以下の状態で Orb を作成できます。

  • 直 URL があり、Orb を作成した組織で認証されていない限り、Orb が CircleCI Orb レジストリに表示されることはありません。

  • 組織外のユーザーは閲覧、使用できません。

  • 組織のものではないパイプラインでは使用できません。

パブリック Orb ではなくプライベート Orb を選択する場合には、プライベート Orb 特有の制限事項も理解する必要があります。具体的には次のとおりです。

  • 設定ファイルの検証に circleci config validate コマンドを使用できなくなります。 しかし、以下のいずれかを選択していただけます。

    • Orb のコンテンツを設定ファイルの orbs スタンザに貼り付けます。
    • circleci config validate --org-id <your-org-id> <path/to/config.yml> を使って設定を検証します。

  • 組織の関係性にかかわらず、ある組織で作成されたプライベート Orb を、別の組織のパイプラインで使用することはできません。 それぞれの組織でコードのコミットとパイプラインの実行に必要なアクセス権を付与されている場合も例外ではなく、プライベート Orb をご自分の設定ファイル内で使うことはできますが、別の Orb からは参照できません。

Orb の作成

パブリック Orb とプライベート Orb はいずれも、2 つの方法で作成できます。

Orb のパッケージ化

すべての CircleCI Orb は単体の YAML ファイルで、通常は orb.yml という名前です。 しかし、開発においては、コードをより管理しやすい塊に分割した方がやり易い場合が多々あります。 circleci orb pack コマンドは、 Orb 開発キットの一部であり、別々の YAML ファイルを「パッケージ化」したり、凝縮したりするために使用されます。

例: Orb プロジェクトの構造

Orb を_パッケージ化_するには、 @orb.ymlファイルが必要です。 @ は、Orb プロジェクトの ルート を示しています。 同じディレクトリ内に、 コマンド、 ジョブ、 Executor、および サンプルなど、Orb コンポーネントの種類ごとに追加のディレクトリを含めることができます。 追加のファイルやフォルダは安全に無視されます。

さらに、 pack コマンドは、Orb 開発者のための特別なプリプロセッサを提供し、 ファイルインクルード構文 （<<include(file)>>）を使って、外部ファイルからコードをインポートすることができます。

CLI コマンド

circleci orb pack <dir> > orb.yml

Orb 開発キットをお使いの場合、この手順は自動的に処理されます。

ファイルインクルード構文

ファイルインクルード構文 (<<include(dir/file)>>) は、CircleCI Orb の設定ファイル内の任意のキーの値として、ファイルの内容をその場で取り込むことができる特別な設定強化機能です。 この<<include(dir/file)>> 構文は、 circleci orb pack コマンド と一緒に使う特別なキーであり、CircleCI 上でより広く動作することは_ありません_。

@orb.ymlファイルを含むディレクトリに対して、circleci orb pack <dir> > orb.yml を実行すると、パッケージ化コマンドが各ファイルの内容を一つの orb.yml ファイルに集め始めます。 パッケージ化の過程で、 <<include(dir/file)>> 値の各インスタンスは、その中で参照されるファイルの内容に置き換えられます。

ファイルインクルード機能は、設定の Bash ロジックをyamlから分離するのに特に有効です。 Bash スクリプトを含めることで、Bash の開発やテストを Orb の外で行うことができます。

Bash スクリプトを含めることに関する詳細は、 Orb 作成者 ガイドをご覧ください。

Orb 内での Orb の使用と登録時の解決

Orb のスタンザは、Orb の中で使うことができます。 安定版 Orb リリースは変更不可なので、Orb 依存関係の解決は、ビルドの実行時ではなく Orb の登録時にすべて行われます。

例えば、biz/baz@volatile をインポートする orbs スタンザを含んだ Orb foo/bar が、バージョン 1.2.3 でパブリッシュされるとします。 foo/bar@1.2.3 を登録する時点で、biz/baz@volatile が最新バージョンとして解決され、その要素がパッケージ バージョンの foo/bar@1.2.3 に直接含められます。

biz/baz が 3.0.0 に更新されても、foo/bar が 1.2.3 よりも上のバージョンでパブリッシュされるまで、foo/bar@1.2.3 を使用しているユーザーには biz/baz@3.0.0 の変更が反映されません。

Orb の要素は、他の Orb の要素を使用して直接構成できます。 例えば、以下の例のような Orb があるとします。

version: 2.1
orbs:
  some-orb: some-ns/some-orb@volatile
executors:
  my-executor: some-orb/their-executor
commands:
  my-command: some-orb/their-command
jobs:
  my-job: some-orb/their-job
  another-job:
    executor: my-executor
    steps:
      - my-command:
          param1: "hello"

関連項目

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