Orbs Introduction

Private orbs vs. public orbs
Benefits of using orbs
The orb registry
Identifying orbs
Using orbs

Quick start

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.

Private orbs

Note: Private orbs are available on any of our paid plans listed on our plans page. Performance plan customers can create up to three private orbs, whereas our Scale plan customers can create an unlimited number of private orbs. Please reach out to your sales representative for more information.

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

your orb does not appear in the CircleCI Orb Registry.
your orb cannot be viewed or used by someone outside of your organization.
your orb cannot be used in a pipeline that does not belong to your organization.

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:

You will be unable to use the circleci config validate command to validate your configuration. You may, however, either paste the content of the orb into the “orbs” stanza of your configuration inline or use the circleci config validate --org-slug <your-org-slug> <path/to/config.yml> command to validate your configuration.
You cannot use private orbs from one organization in another organization’s pipelines, regardless of the relationship between organizations. This means that even if you commit code and start a pipeline, and have the necessary membership in both organizations, you can use a private orb from your configuration file, but not from another orb.

Public 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.

Authoring orbs

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

Using the Manual Orb Authoring Process
Using the Orb Development Kit (recommended)

Benefits of using 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

The orb registry

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.

Identifying 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

Using 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 example

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