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.
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. Descriptions of each type of orb is described in the sections below.
Private orbs
Note: Private orbs are available on our Scale Plan. Please reach out to your sales representative for information on how to sign up for the Scale Plan.
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 thecircleci 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.
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
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.