Skip to content
Docs
Cancel

Orb の概要

クイック スタート

CircleCI orbs are open-source, shareable packages of parameterizable reusable configuration elements, including jobs, commands, and executors. Use orbs to reduce configuration complexity and help you integrate with your software and services stack quickly and easily across many projects.

Published orbs can be found on our Orb Registry, or you can author your own orb.

Private orbs vs. public orbs

There are two different types of orbs you can use in your configuration, depending on how you want to publish your orbs. If you prefer to publish your orb internally, and not to the CircleCI Orb Registry, you will want to use a private orb. However, if you want to publish your orb to the CircleCI Orb Registry, use a public orb. Each type of orb is described in the sections below.

プライベート Orbs

メモ: プライベート Orbs 機能は、いずれかの有料プランで利用いただけます。パフォーマンスプランのお客様は最大3つのプライベート Orbs まで作成でき、スケールプランのお客様はプライベート Orbs の作成上限数に制限はありません。詳細については、営業担当者へお問い合わせください。

Using a private orb enables you to author an orb while ensuring the following:

  • CircleCI Orb レジストリに公開されない。

  • 作成元組織以外のユーザーは閲覧、使用できない。

  • 作成元組織のものではないパイプラインでは使用できない。

By choosing to use a private orb instead of a public orb, you also need to understand certain limitations inherent in using private orbs, which include:

  • 設定ファイルのバリデーションに circleci config validate コマンドを使用できなくなります。 その代わり、Orb のコンテンツを設定ファイルの “orbs” スタンザにインラインで貼り付けるか、circleci config validate --org-slug <your-org-slug> <path/to/config.yml> コマンドを使用することで、設定ファイルをバリデーションできます。

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

パブリック Orbs

Public orbs are used by most users when authoring and publishing orbs to the CircleCI Orb Registry. When authoring a public orb, you are enabling all CircleCI users to use your orb in their own configurations.

Orb のオーサリング

Both public and private orbs can be authored in two ways:

Orbs を使用するメリット

Orbs provide parameterizable configuration elements that can greatly simplify your configuration. To illustrate this, the following example shows a typical configuration for testing a Node.js application – defining a job with the required steps for testing the application – versus using the test job provided by the circleci/node orb. With orbs, it is possible to write a parameterized configuration once and utilize it across multiple similar projects.

version: 2.1

orbs:
  node: circleci/node@x.y #orb version

workflows:
  test_my_app:
    jobs:
      - node/test:
          version: <node-version>

version: 2.1

jobs:
  test:
    docker:
      - image: cimg/node:<node-version>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - restore_cache:
          keys:
            - node-deps-v1-{{ .Branch }}-{{checksum "package-lock.json"}}
      - run:
          name: install packages
          command: npm ci
      - save_cache:
          key: node-deps-v1-{{ .Branch }}-{{checksum "package-lock.json"}}
          paths:
            - ~/.npm
      - run:
          name: Run Tests
          command: npm run test

workflows:
  test_my_app:
    jobs:
      - test

Orb レジストリ

The Orb Registry is an open repository of all published orbs. Find the orb for your stack or consider developing and publishing your own orb.

Orb Registry

Orbs in the registry will appear with one of three different namespace designations:

Certified Written and tested by the CircleCI team   Partner Written by our technology partners   Community Written by the community

Note: In order to use uncertified orbs, your organization’s administrator must opt-in to allow 3rd-party uncertified orb usage on the Organization Settings > Security page for your org.

Each orb contains its own description and documentation listed in the orb registry. Often, orbs will have a set of usage examples to get you started.

If you would like to contribute to an existing orb or file an issue on the orb’s repository, many orb authors will include the git repository link.

Orbs の指定

An orb is identified by its slug which contains the namespace and orb name. A namespace is a unique identifier referring to the organization authoring a set of orbs. The orb name will be followed be an @ symbol and a semantic version string, identifying which version of the orb is being used.

Example orb slug: <namespace>/<orb-name>@1.2.3

Orbs の使用

Each orb within the registry provides a sample code snippet for importing that specific orb with its most recent version.

The example below shows how to import an orb into your version: 2.1 config file. Create an orbs key followed by the orb-name key to reference which orb you want to import. The value for the orb-name key should then be the orb slug and version.

version: 2.1

orbs:
  orb-name: <namespace>/<orb-name>@1.2.3

After the orb has been imported into the configuration file, the elements provided by the orb are available as <orb-name>/<element>. Orb elements can be used in the same way as reusable configuration elements. The Node example below shows how to use an orb command.

Node の例

The Node orb provides a command, install-packages, to install your node packages, automatically enable caching, and provide additional options through the use of parameters. To use the install-packages command, reference it in a job’s steps.

version: 2.1

orbs:
  node: circleci/node@x.y #orb version

jobs:
  test:
    docker:
      - image: cimg/node:<node-version>
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - node/install-packages # Utilize commands in steps

関連項目


Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.

Creative Commons License
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.