Orb のコンセプト

クイックスタート

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 の定義例

description: >
  使用する Node.js のバージョンを選択。 CI 用にビルドされ高度にキャッシュされた Circle CI の便利なイメージを使用:
  - image: 'cimg/node:<<parameters.tag>>'
    auth:
      username: mydockerhub-user
      password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
parameters:
  tag:
    default: '13.11'
    description: >
      Pick a specific cimg/node image version tag:
      https://hub.docker.com/r/cimg/node
    type: string
description: >
  使用する Ruby のバージョンを選択。 CI 用にビルドされ高度にキャッシュされた Circle CI の便利なイメージを使用:
  images built for CI.

  CI 用にビルドされ高度にキャッシュされた Circle CI の便利なイメージを使用:

  このリストの中から利用可能なタグを使用することができます。
  https://hub.docker.com/r/cimg/ruby/tags
docker:
  - image:'cimg/ruby:<< parameters.tag >>'
    auth:
      username: mydockerhub-user
      password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
parameters:
  tag:
    default: '2.7'
    description:`circleci/ruby` の Docker イメージのバージョンを示すタグ
    type: string
    type: string

例えば、 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 ディレクトリ内に nam-of-example.yml という新しいファイルを作成するだけです。 使用例は、プロジェクトの設定に直接使用するものではありませんが、ユーザーが自分の設定における Orb の最適な使用方法を共有するための一種の Orb メタデータであり、Orbレジストリに参照用に表示されています。 以下は使用例のサンプルです。

# ソース https://github.com/circleci-public/orb-project-template/blob/master/src/examples/example.yml

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 オーサーはセマンティック バージョン管理を厳密に行い、 マイナー または パッチ レベルの更新時に大きな変更が取り込まれないようにする必要があります。

注: CircleCI は現在、数字以外のセマンティック バージョニング要素をサポートしていません。 x.y.z 形式のセマンティック バージョニング スタイルのバージョン文字列、またはdev:*形式の開発スタイルのバージョン文字列を使用することをお勧めします。

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 のパッケージ化

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

Orb 開発キットを使用している場合、オーブのパッケージ化は、付属のCI/CDパイプラインによって、 orb-tools/pack ジョブで自動的に処理されます。

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

種類 名前
コマンド
Executor
ジョブ
@orb.yml

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)>> 値の各インスタンスは、その中で参照されるファイルの内容に置き換えられます。

含まれるファイルは常に @orb.yml ファイルの相対的な位置から参照されます。

description: パッケージ化時にファイルからインポートする簡単なコマンド
steps:
  - run:
      name: Hello Greeting
      command: <<include(scripts/file.sh)>>
# これは bash ファイルですが、テキストベースのファイルであれば何でも構いません
echo "Hello World"

description: パッケージ化時にファイルからインポートする簡単なコマンド
steps:
  - run:
      name: Hello Greeting
      command: |
        # これは Bash ファイルですが、テキストベースのファイルであれば何でも構いません。
        echo "Hello World"

ファイルインクルード機能は、設定の 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/baz3.0.0 に更新されても、foo/bar1.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"

関連項目



ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースで、GitHub で使用できます。 ご協力いただき、ありがとうございます。


クリエイティブ・コモンズ・ライセンス
CircleCICircleCI ドキュメントは、クリエイティブ・コモンズの表示--非営利-継承 4.0 国際ライセンス に基づいてライセンス供与されています。