Orbs overview

Introduction

Orbs are reusable packages of parameterizable configuration that can be used in any project. They are made up of reusable configuration elements, for example: * jobs * commands * executors.

CircleCI supports two types of orbs:

Registry orbs: Orbs that are developed and published using the orb publishing process. SemVer-based versioning is used to manage the versions of registry orbs. Registry orbs are available from the Orbs Registry
URL orbs: Orbs that are stored in a publicly accessible location (for example, a git repository or a public S3 object) and are not published to the orbs registry. URL orbs do not follow semantic versioning, and can be accessed directly using an https URL. An org-level allow list is used to manage the addresses of URL orbs that can be used in a project in that organization. Manage the allow list at Organization Settings Orbs. See the Managing URL orb allow-lists guide for more information on scoping allowed URL orbs for your organization.

Orbs are available for many languages, platforms, services, and tools. Visit the Orbs Registry to search for orbs to help simplify your configuration.

If you would like to author your own orb, read more on the Introduction to Authoring Orbs page.

Quickstart

Follow our Node.js project quickstart guide.
Follow our Python project quickstart guide.
Set up notifications using the Slack orb.

Use a registry orb

A registry 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 by an @ symbol and a semantic version string, identifying which version of the orb is being used. For example: <namespace>/<orb-name>@1.2.3.

Each orb within the registry provides a quickstart guide, which contains a sample code snippet for importing that specific orb, with its most recent version, into your .circleci/config.yml.

The example below shows how to import any orb into your CircleCI configuration file. Use the tabs to switch between a generic layout for importing any orb, and a specific example of importing the Node.JS orb:

version: 2.1

orbs:
  node: circleci/node@5.0.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 include jobs, commands, and executors. The parameters available for each element are listed in the orb registry in a table under each element.

Most orbs will also include usage examples detailing common functionality, to further simplify the process of incorporating them into your projects. 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.

Orb elements can be used in the same way as reusable configuration elements. The Node example below shows how to use an orb’s default executor, and 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 # replace orb version

jobs:
  test:
    executor: node/default # use the default executor specified by the orb
    steps:
      - checkout
      - node/install-packages # Use a command from the orb in a job's steps

Use a URL orb

To use a URL orb in your configuration, add the orb to the orbs section of your configuration file using the https URL of the orb repository. The URL must point to a repository that is accessible to CircleCI and must be allowed by the organization’s allow list.

The following example shows how to import a URL orb named platform into your configuration file. To use this orb, the https://raw.githubusercontent.com/my-org/ prefix must exist in your org’s allow list.

version: 2.1

orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/refs/heads/main/platform-team.yaml

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 include jobs, commands, and executors.

Benefits of using orbs

Orbs provide parameterizable configuration elements that can greatly simplify your configuration. To illustrate this, the following example shows the following:

A typical configuration for testing a Node.js application using the Node.JS orb (using the test job provided by the circleci/node orb).
Configuration required without using the orb (defining a job with the required steps for testing the application).

Orbs let you pull in pre-defined, parameterized configuration elements into your project configuration. Taking it a step further, authoring your own orb lets you define parameterized configuration elements once and utilize them across multiple similar projects.

version: 2.1

orbs:
  node: circleci/node@x.y # replace orb version https://circleci.com/developer/orbs/orb/circleci/node#quick-start

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

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.

Registry orb designations

In order to use uncertified registry orbs (partner or community), your organization’s administrator must opt-in to allow uncertified orb usage on the Security page for your org.

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

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

Public or private

Orbs can be published in one of two ways:

Public: Searchable in the orb registry, and available for anyone to use
Private: Only available to use within your organization, and only findable in the registry with a direct URL and when authenticated

To understand these concepts further, read the Public Orbs vs Private Orbs section of the Orb Concepts page.

Orbs page in the CircleCI app

The orbs page in the CircleCI web app is not currently available on CircleCI server.

Private orb details pages may only be viewed by logged-in members of your organization. Unpublished orbs will not have linked details pages.

To access the orbs page in the web app, navigate to Organization Settings and select Orbs from the sidebar.

The orbs page lists orbs created within your organization. You can view:

Orb type (public or private)
Orb usage (how many times the orb is used across all configurations)
Latest version
Description

Full orb details, including orb source, are accessible by clicking on the orb name. The orb details page is similar to the CircleCI orb registry in that the details page provides the orb’s contents, commands, and usage examples.

The orbs page also includes your org’s allow list URLs for URL orbs.

On This Page