Use orbs to:
- Simplify configuration (
- Automate repeated processes
- Accelerate project setup
- Simplify integration with third-party tools
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, and executors. 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.
- Follow our Node.js project quickstart guide.
- Follow our Python project quickstart guide.
- Set up notifications using the Slack orb.
Use an orb
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 by an
@ symbol and a semantic version string, identifying which version of the orb is being used. For example:
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
The example below shows how to import any orb into your CircleCI configuration file. There are two tabs to show both a generic layout for importing any orb, and a specific example of importing the Node.JS orb:
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.
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: email@example.com # 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
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 using the Node.JS orb (using the
test job provided by the
circleci/node orb), compared to the 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.
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|
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
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
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.
- 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.
- 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.
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.