Orbs Introduction

today • 2 min read

Cloud Server v3.x

• Benefits of using orbs
• The orb registry
• Public or private
• Identifying orbs
• Using orbs
• Orbs page in the CircleCI app
• Learn More

Orbs are reusable snippets of code that help automate repeated processes, accelerate project setup, and make it easy to integrate with third-party tools. Visit the Orbs Registry on the CircleCI Developer Hub to search for orbs to help simplify your configuration.

Examples of reusable snippets that can be included in orbs are jobs, commands, executors, as well as Node.js and its package managers.

Use orbs to reduce configuration complexity, and help you integrate with your software and services stack quickly and easily across many projects.

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

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.

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

Note: In order to use uncertified orbs (partner or community), your organization’s administrator must opt-in to allow 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.

Public or private

Orbs can be published in one of two ways:

• Publicly: Searchable in the orb registry, and available for anyone to use
• Privately: 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.

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

Orbs page in the CircleCI app

The Orbs page gives users visibility into the orbs their organization has created. Users can review the orb type (public or private), orb usage (how many times the orb is used across all configurations), latest version, and description directly from the list view on the page.

To access the Orbs page, navigate to Organization Settings in the app.

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. Note: Private orb details pages may only be viewed by logged-in members of your organization. Unpublished orbs will not have linked details pages.

See also

• Refer to Orbs Concepts for high-level information about CircleCI orbs.
• Refer to Orbs FAQ for information on known issues and questions that have been addressed when using CircleCI orbs.
• Refer to Reusable Configuration Reference for examples of reusable orbs, commands, parameters, and executors.
• Refer to Orb Testing Methodologies for information on how to test orbs you have created.

Learn More

Take the orbs course with CircleCI academy to learn more.

---

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.

• Suggest an edit to this page (please read the contributing guide first).
• To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
• CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

---

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