CircleCI Logo
Navigation Menu Icon

Introduction to authoring orbs

Language Icon 18 days ago
Cloud Server v4+

CircleCI orbs are packages of Reusable Configuration that you can import into your CircleCI configuration files. Orbs are available in three types:

Registry orbs

Registry orbs can be developed using the orb dev kit (there is also a manual process) and published for use by anyone (public) or within your organization (private). Registry orbs follow strict semantic versioning. Public registry orbs are available from the Orbs Registry.

Registry 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 registry orb, read more on the Create a Registry Orb page.

URL orbs

URL orbs 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. Organization admins can 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.

If you would like to author your own URL orb, see the Create, Test, and Use URL Orbs guide.

Inline orbs

Inline orbs are defined directly within your project’s configuration file. They are project-specific and not published or shared externally. Inline orbs are ideal for reusable configuration within a single project, and are also useful for learning orb concepts and testing configurations prior to extracting to a URL or registry orb.

Inline orbs do not require publishing, versioning, or external hosting. They exist only within your .circleci/config.yml file.

See the Create an Inline Orb guide for more information on creating inline orbs.

If you manage multiple, similar projects, consider abstracting out your config with orbs.

Prerequisites

Before authoring an orb, we recommend that you become familiar with the Configuration Reference and authoring Reusable Configuration Reference pages.

Orbs consist of three main elements. You can follow the links for each to learn more:

  • Commands. A CircleCI command is a reusable block of configuration that can be called multiple times in your configuration.

  • Jobs. A CircleCI job is a collection of steps that run commands or scripts inside a specified executor (like a Docker container or virtual machine).

  • Executors. A CircleCI executor is a specified environment in which to run a job.

Getting started with creating a registry orb

Registry orb authors automatically agree to the CircleCI Code Sharing Terms of Service. All publicly published orbs are made available on the Orb Registry under the MIT License agreement. For more information, see Orb Licensing.

Once a registry orb is created it cannot be deleted. Registry orbs are SemVer compliant, and each published version is immutable. Publicly released orbs are potential dependencies for other projects. Therefore, allowing orb deletion would make users susceptible to unexpected loss of functionality.

We recommend using our Orb development kit to create a registry orb. A full guide is available in the Create, Test, and Publish a Registry Orb guide.

Alternatively, as orbs are packages of Reusable Configuration, they can be written manually too, as singular yaml files, and published using our CircleCI Orb CLI. For a guide, see the Manual Orb Authoring Process page.

Getting started with creating a URL orb

URL orbs are reusable CircleCI configuration stored in an accessible location like a Git repository.

See the Create, Test, and Use URL Orbs guide for steps to create and use a URL orb.

URL orbs are particularly useful for:

  • Sharing configuration across your organization.

  • Using proprietary or confidential configurations.

  • Direct control over updates and distribution.

  • Bypassing the orb publishing process and semantic versioning.

Getting started with creating an inline orb

Inline orbs are the simplest way to create reusable configuration within a single project. They require no setup, publishing, or external hosting.

To create an inline orb, define it directly in your .circleci/config.yml file using the orbs stanza. For a complete guide and examples, see the Create an Inline Orb guide.

Inline orbs are particularly useful for:

  • Learning orb concepts and syntax.

  • Testing reusable configuration before converting to a URL orb or registry orb.

  • Project-specific helper commands and jobs that do not need to be shared.

Orb development tools (registry orbs only)

The tools in this section apply to registry orbs only.

Orb development kit

The orb development kit refers to a suite of tools that work together to simplify the registry orb development process, with automatic testing and deployment on CircleCI. The orb init command is the key to using the orb development kit. This command initiates a new orb project based on a template, and that template uses the other tools in the kit to automatically test and deploy your orb.

The orb development kit is made up of the following components:

The orb template is a repository with CircleCI’s orb project template, which is automatically ingested and modified by the orb init command.

The CircleCI CLI contains two commands which are designed to work with the kit. The orb init command initializes a new orb project, and the orb pack command packs the orb source into a single orb.yml file.

The orb tools orb is an orb for creating orbs.

Orb CLI

To begin creating orbs, follow the CircleCI CLI Installation guide on your local machine, with a personal access token. For a full list of orb-related commands inside the CircleCI CLI, visit CircleCI CLI help.

Permissions matrix

Orb CLI commands are scoped to different user permission levels, set by your VCS. You are the owner of your own organization. If you are authoring or publishing registry orbs for a namespace owned by another organization, you may require assistance from your organization admin:

Orb Command Permission Scope

circleci namespace create

Owner

circleci orb init

Owner

circleci orb create

Owner

circleci orb publish development version

Member

circleci orb publish production version

Owner

Listing and categorizing registry orbs

Listing your orbs

List your available orbs using the CLI:

To list Public orbs:

circleci orb list <my-namespace>

To list Private orbs:

circleci orb list <my-namespace> --private

For more information on how to use the circleci orb command, see the CLI documentation.

Categorizing your orb

Orb categorization is not available on installations of CircleCI Server.

You can categorize your orb for better discoverability in the Orb Registry. Categorized orbs are searchable by category in the Orb Registry. CircleCI may, from time to time, create or edit orb categorizations to improve orb discoverability.

Listing categories

Example of showing listing categories using the CLI
Figure 1. Example of showing listing categories using the CLI

You can select up to two categories for your orb. These are the available categories:

  • Artifacts/Registry

  • Build

  • Cloud Platform

  • Code Analysis

  • Collaboration

  • Containers

  • Deployment

  • Infra Automation

  • Kubernetes

  • Language/Framework

  • Monitoring

  • Notifications

  • Reporting

  • Security

  • Testing

The list of categories can also be obtained by running the circleci orb list-categories CLI command. You can view the detailed docs for this command in the CLI documentation.

Add an orb to a category

Adding an orb category
Figure 2. Adding an orb category

Add your orb to your chosen category by running circleci orb add-to-category <namespace>/<orb> "<category-name>". You can view the detailed docs for this command in the CLI documentation.

Remove an orb from a category

Removing an orb from a category
Figure 3. Removing an orb from a category

Remove an orb from a category by running circleci orb remove-from-category <namespace>/<orb> "<category-name>". You can view the detailed docs for this command in the CLI documentation.

Viewing an orb’s categorizations

Show which categorizations have been added to an orb
Figure 4. Show which categorizations have been added to an orb

To see which categorizations have been applied an orb, check the output of circleci orb info <namespace>/<orb> for a list. You can view the detailed docs for this command in the CLI documentation.