Search Results for ""

Orbs Introduction

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.

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>
    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>
    steps:
      - checkout
      - node/install-packages # Utilize commands in steps

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.
  • Refer to Configuration Cookbook for information about how you can use CircleCI orb recipes in your configurations.