Orb の概要

version 2.1 のクラウド版 CircleCI で利用可能です。オンプレミス版では現在サポートされていません。

CircleCI Orbs は、ジョブ、コマンド、Executor などの構成要素をまとめた共有可能なパッケージです。 CircleCI では承認済み Orbs に加え、CircleCI パートナーによってオーサリングされたサードパーティ製の Orbs も提供しています。まずは、こうした既存の Orbs がご自身の構成ワークフローに活用できるかどうかを評価することをお勧めします。承認済み Orb の一覧は、CircleCI Orb レジストリにて確認してください。

CircleCI Orbs の使用

ワークフローやジョブに CircleCI Orbs を使用するには、いくつかの方法があります。 CircleCI Orb レジストリから既存の Orb (CircleCI およびパートナー承認済み Orbs) をインポートする方法か、特定のワークフロー用に独自の Orb をオーサリングする方法を選ぶ場合が多いでしょう。それぞれのアプローチについて以下に説明します。

既存の Orb をインポートする

既存の Orb をインポートするには、以下の手順を行います。

1) 各 Orb のバージョン 2.1 .circleci/config.yml ファイルに以下の 1 行を追加します。

version: 2.1

メモ: 2.1 よりも前のバージョンで CircleCI に追加されていたプロジェクトでは、パイプラインを有効化して orbs キーを使用できるようにする必要があります。

2) バージョンの下に orbs スタンザを追加し、Orbs を呼び出します。以下に例を示します。

orbs:
  slack: circleci/slack@0.1.0
  heroku: circleci/heroku@0.0.1

上記の例では、2 つの Orb が設定ファイルにインポートされます。

パートナーの Orb をインポートする

パートナーの Orb をインポートするには、以下の手順を行います。

1) 構成内の .circleci.yml/config.yml ファイルで orbs キーをインポートします。

2) 下の例の <Orb 参照文字列> の値を CircleCI Orb レジストリからインポートする Orb に置き換えます。レジストリには数多くの CircleCI 承認済み Orb およびパートナー承認済み Orbs が公開されており、必要なものを利用できます。

version: 2.1

orbs:
  <Orb 参照文字列>

CircleCI Orb レジストリで提供されているパートナー Orb の例

CircleCI Orb レジストリから入手できる数多くの Orb の中から、一部をご紹介します。

Partner Orb レジストリリンク	Orbs 参照文字列
Alcide-io	`alcide: alcideio/alcide-advisor@1.0.3`
Anchore	`anchore: anchore/anchore-engine@1.0.0`
Aqua Security	`aqua: aquasecurity/microscanner@0.0.1`
AWS CLI	`cli: circleci/aws-cli@0.1.13`
AWS CodeDeploy	`codedeploy: circleci/aws-code-deploy@0.0.9`
Amazon ECR	`ecr: circleci/aws-ecr@4.0.1`
Amazon ECS	`ecs: circleci/aws-ecs@0.0.11`
Amazon EKS	`eks: circleci/aws-eks@0.1.0`
AWS パラメータストア	`awsparameter: circleci/aws-parameter-store@1.0.0`
AWS S3	`s3: circleci/aws-s3@1.0.11`
Azure ACR	`acr: circleci/azure-acr@0.1.1`
Azure AKS	`aks: circleci/azure-aks@0.1.0`
Azure CLI	`cli: circleci/azure-cli@1.1.0`
Cloudsmith	`cloudsmith: cloudsmith/cloudsmith@1.0.3`
Codecov	`codecov: codecov/codecov@1.0.1`
CodeScene	`codescene: empear/codescene-ci-cd@1.0.0`
ConfigCat	`configcat: configcat/flag_reference_validator@1.0.3`
Contrast Security	`contrastsecurity: contrastsecurity/verify@0.1.2`
Convox	`convox: convox/orb@1.4.1`
Cypress-io	`cypress-io: cypress-io/cypress@1.0.0`
Datree	`datree: datree/policy@1.0.6`
DeployHub	`deployhub: deployhub/deployhub-orb@1.2.0`
Docker Hub	`dockerhub: circleci/docker@0.1.0`
FØCAL	`f0cal: f0cal/farm@1.0.0`
Fairwinds	`fairwinds: fairwinds/rok8s-scripts@9.4.0`
Fortanix	`fortanix: fortanix/sdkms-cli@1.0.0`
FOSSA	`fossa: fossa/cli@0.0.3`
Ghost Inspector	`ghostinspector: ghostinspector/test-runner@1.0.0`
GCP Bin Auth	`gcp: circleci/gcp-binary-authorization@0.5.2`
Google Cloud CLI	`gcpcli: circleci/gcp-cli@1.8.2`
Google Container Registry	`gcr: circleci/gcp-gcr@0.0.7`
Google Kubernetes Engine	`gke: circleci/gcp-gke@0.1.0`
Happo	`happo: happo/happo@1.0.1`
Helm	`helm: circleci/helm@0.1.1`
Honeybadger-io	`honeybadger-io: honeybadger-io/deploy@1.1.1`
Honeycomb	`buildevents: honeycombio/buildevents@0.1.1`
JFrog	`jfrog: circleci/artifactory@1.0.0`
Kublr	`kublr: kublr/kublr-api@0.0.1`
LambdaTest	`lambdatest: lambdatest/lambda-tunnel@0.0.1`
LaunchDarkly	`launchdarkly: launchdarkly/ld-find-code-refs@1.2.0`
LogDNA	`logdna: logdna/logdna@0.0.1`
Neocortix	`neocortix: neocortix/loadtest@0.4.0`
NeuVector	`neuvector: neuvector/neuvector-orb@1.0.0`
Nirmata	`nirmata: nirmata/nirmata@1.1.0`
NowSecure	`nowsecure: nowsecure/ci-auto-orb@1.0.5`
Oxygen	`oxygen: cloudbeat/oxygen@1.0.0`
PackageCloud	`packagecloud: packagecloud/packagecloud@0.1.0`
packtracker.io	`packtracker: packtracker/report@2.2.2`
Pantheon	`pantheon: pantheon-systems/pantheon@0.1.0`
Percy	`percy: percy/agent@0.1.2`
Postman	`postman: postman/newman@0.0.1`
Probely	`probely: probely/security-scan@1.0.0`
Provar	`provar: provartesting/provar@1.9.10`
Pulumi	`pulumi: pulumi/pulumi@1.0.0`
Quali	`quali: quali/cloudshell-colony@1.0.4`
realMethods	`realmethods: realmethods/appgen@1.0.1`
Red Hat OpenShift	`redhat: circleci/redhat-openshift@0.1.0`
Rocro	`rocro: rocro/inspecode@1.0.0`
Rollbar	`rollbar: rollbar/deploy@1.0.1`
Rookout	`rookout: rookout/rookout-node@0.0.2`
Sauce Labs	`saucelabs: saucelabs/sauce-connect@1.0.1`
Snyk	`snyk: snyk/snyk@0.0.8`
Sonatype	`sonatype: sonatype/nexus-platform-orb@1.0.2`
Styra	`styra: styra/cli@0.0.7`
Sumo Logic	`sumologic: circleci/sumologic@1.0.0`
Testim	`testim: testimio/runner@1.1.1`
Twistlock	`twistlock: twistlock/twistcli-scan@1.0.4`
Unmock	`unmock: unmock/unmock@0.0.10`
VMware Code Stream	`vmware: vmware/codestream@1.0.0`
WhiteSource	`whitesource: whitesource/whitesource-scan@18.10.2`
WhiteSource Vulnerability Checker	`whitesource: whitesource/vulnerability-checker@19.7.2`
xMatters	`xmatters: xmatters/xmatters-orb@0.0.1`

メモ: 前提条件として、組織の [Settings (設定)] > [Security (セキュリティ)] ページでサードパーティ製 Orbs の使用を有効化する必要があります。

独自の Orb をオーサリングする

既存の Orb ではニーズを満たせない場合、以下の circleci orb help の出力に示されている CircleCI CLI を使用して、特定の環境や構成要件に合った独自の Orb をオーサリングできます。インポート機能を使用する場合に比べて時間はかかりますが、独自 Orb をオーサリングすると、グローバルに読み取り可能な Orb を作成して自身の構成を共有することが可能です。詳細については、Orbs の作成に関するドキュメントを参照してください。

メモ: パブリッシュ済みの Orb をレジストリのリストから除外するには、circleci orb unlist CLI コマンドを使用します。詳細については、ヘルプページを参照してください。リストから除外した Orb は、名前で参照すれば引き続きグローバルに読み取り可能ですが、Orb レジストリの検索結果には表示されません。リストから除外した後も、circleci orb unlist <namespace/orb> false コマンドを使用して再度リストに戻すことができます。

$ circleci orb help
Operate on orbs

Usage:
  circleci orb [command]

Available Commands:
  create      指定された名前空間に Orb を作成します
  info        Orb のメタデータを表示します
  list        Orb をリストに含めます
  process     事前登録処理後に Orb のバリデーションを行い、Orb の形式を出力します
  publish     Orb をレジストリにパブリッシュします
  source      Orb のソースを表示します
  validate    orb.yml のバリデーションを行います  

メモ: Orb をオーサリングするには、組織がサードパーティ製 Orb の使用とオーサリングをオプトインし、CircleCI のコード共有利用規約に同意する必要があります。 CircleCI はそれを受けて、MIT ライセンス契約に基づき、すべての Orb のライセンスをユーザーに付与します。