CircleCI Logo
Navigation Menu Icon

Orbs concepts

Language Icon 3 days ago
Cloud Server v4+
Contribute Go to Code

CircleCI orbs are shareable packages of configuration elements, including the following:

  • 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).

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

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

Orbs make writing and customizing CircleCI config simple. The reusable configuration elements used in orbs are explained fully in the Reusable Configuration Reference.

Orb types

CircleCI supports three types of orbs:

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.

Orb types comparison

The following table provides a detailed comparison of the three orb types:

Feature Registry Orbs URL Orbs Inline Orbs

Location

Published to Orb Registry, stored in GitHub repository

Hosted at accessible URL (GitHub, S3, etc.)

Defined in config file

Sharing scope

Public or private across organizations

Organization-wide (with allow-list)

Project-specific only

Versioning

Semantic versioning

Manual (Git branches, tags, commits)

None

VCS support

Registry orbs are hosted in GitHub only but can be used by all CircleCI users if public

GitHub, Bitbucket

GitHub, GitLab, Bitbucket

Mutability

Immutable

Mutable

Mutable (edit config directly)

Updates

Publish new semantic version (immutable)

Update hosted file (5-minute cache)

Edit config file directly

Access control

Namespace permissions

Organization allow-list

Repository access only

Best for

Community sharing, public packages, certified orbs

Organization-wide shared config, overriding config, proprietary logic

Project-specific reusable config, learning, testing

Choose this type when:

  • You want to share your orb with the community.

  • You want to use semantic versioning for your orb.

  • You want your orb to be discoverable in the CircleCI Orb Registry.

  • You want to leverage the orb development kit and automated CI/CD pipeline.

  • You want to use centralized configuration for your organization.

  • You need to share configuration within your organization.

  • You need direct control over updates and distribution.

  • You need to use proprietary or confidential configurations.

  • Configuration is specific to a single project.

  • You want zero publishing or hosting overhead.

  • You’re learning about orbs and want to experiment.

  • You need immediate changes without any publishing delay.

Orb configuration elements

CircleCI’s Reusable Configuration features allow you to define parameterizable configuration elements and re-use those elements throughout a project config file.

Commands

Commands contain one or more steps in which Parameters can be used to modify behavior. Commands are the logic of orbs and are responsible for executing steps such as Checking Out Code, or running shell code, for example, running Bash or CLI tools. For more information see the Authoring Reusable Commands guide.

As an example, the AWS S3 orb includes a command to copy a file or object to a new location: aws-s3/copy. If your AWS authentication details are stored as environment variables, the syntax to use this command in your config is simply:

version: 2.1

orbs:
  aws-s3: circleci/aws-s3@4.1.0

jobs:
  build:
    docker:
      - image: 'cimg/python:3.6'
    steps:
      - checkout
      - run: mkdir bucket && echo "lorem ipsum" > bucket/build_asset.txt
      # using the aws-s3 orb's "copy" command.
      - aws-s3/copy:
          from: bucket/build_asset.txt
          to: 's3://my-s3-bucket-name'

  #... workflows , other jobs etc.

See the AWS-S3 Orb page in the registry for more information.

Executors

Executors are parameterized execution environments in which Jobs can be run. CircleCI provides multiple executor options:

  • Docker

  • macOS

  • Windows

  • Machine (Linux VM)

Executors defined within orbs can be used to run jobs within your project configuration, or within the jobs defined in the orb.

Executor definition example

  • Node-Docker

  • Ruby-Docker

description: >
  Select the version of NodeJS to use. Uses CircleCI's highly cached convenience
  images built for CI.
docker:
  - image: 'cimg/node:<<parameters.tag>>'
parameters:
  tag:
    default: '13.11'
    description: >
      Pick a specific cimg/node image version tag:
      https://circleci.com/developer/images/image/cimg/node
    type: string
description: >
  Select the version of Ruby to use. Uses CircleCI's highly cached convenience
  images built for CI.

  Any available tag from this list can be used:
  https://hub.docker.com/r/cimg/ruby/tags
docker:
  - image: 'cimg/ruby:<< parameters.tag >>'
parameters:
  tag:
    default: '2.7'
    description: The `circleci/ruby` Docker image version tag.
    type: string

In the Node orb, for example, a parameterized Docker-based executor is provided, through which you can set the Docker tag. This provides a simple way to test applications against any version of Node.js when used with the Node orb’s test job.

For more information, see the guide to Authoring Reusable Executors and example for the executor parameter type. Also, see the registry page for the Node Orb.

Jobs

Jobs define a collection of steps to be run within a given executor, and are orchestrated using Workflows. Jobs will also individually return their status via GitHub Checks.

When importing an orb which has jobs, you can reference them directly from your workflows.

version: 2.1

orbs:
  <orb>: <namespace>/<orb>@x.y #orb version

workflows:
  use-orb-job:
    jobs:
      - <orb>/<job-name>

See the Authoring Reusable Jobs guide for more information, and the Using Node Test Job example in the orb registry.

Usage examples (registry orbs only)

Using the Orb Development Kit, adding a new usage example is as simple as creating a new file name-of-example.yml within the orb project’s src/examples directory.

Usage examples are not for use in project configuration directly. They are a type of orb metadata to share how a user could best make use of the orb in their configuration. These examples are displayed, for reference purposes, in the Orb Registry. Below is a sample usage example:

Example of a usage example for a registry orb
# Source https://github.com/circleci-public/Orb-Template/blob/main/src/examples/example.yml

description: >
  Sample example description.
usage:
  version: 2.1
  orbs:
    <orb-name>: <namespace>/<orb-name>@1.2.3
  workflows:
    use-my-orb:
      jobs:
        - <orb-name>/<job-name>

Namespaces (registry orbs only)

A namespace is a unique identifier claimed by a user or organization to group a set of registry orbs by author. Each user or organization can claim one unique and immutable namespace. Each namespace can contain many uniquely named registry orbs.

For example, the circleci/rails orb may coexist in the registry with an orb called <other-namespace>/rails because they are in separate namespaces.

Organizations are, by default, limited to claiming only one namespace. This policy is designed to limit name-squatting and namespace noise. If you need to change your namespace, contact support.

By default, created namespaces appear as "community" namespaces in the Orb Registry.

Semantic versioning (registry orbs only)

Registry orbs use the SemVer release process, in which each orb update follows a standardized versioning pattern that orb authors and users should take advantage of.

In Semantic versioning, release versions are represented by three integers separated by a ., where each integer represents a different type of change being added.

[Major].[Minor].[Patch]
SemVer Description

Major

Breaking changes.

Minor

Backwards compatible additional features.

Patch

Bug fixes.

When you import a registry orb, you can pin it to a particular SemVer component.

Imported Version Description

1.2.3

Will match full SemVer version. No changes will be introduced.

1.2

Locked to major version 1, minor version 2, will receive all patch updates.

1

Locked to major version 1. Will receive all minor and patch updates. Major version will not change automatically.

volatile

Not Recommended Will pull the last published version of the orb, may be useful in testing. Not a part of SemVer versioning.

To avoid negatively impacting a user’s CI process, orb authors should strictly adhere to SemVer versioning to ensure no breaking changes are introduced at the minor or patch update levels.

CircleCI does not currently support non-numeric semantic versioning elements. We suggest that you use either SemVer-style version strings in x.y.z format, or a development-style version string in dev:* format.

Registry orb versions (development vs production)

This section applies to registry orbs only. Inline orbs and URL orbs do not use the registry orb versioning system.

Registry orbs can be published in two states:

  • Production (immutable, semantic versioned).

  • Development (mutable, temporary).

Production registry orbs

Production registry orbs are immutable and can be found on the Orb Registry.

Production registry orbs:

  • Are immutable—they cannot be deleted or edited, and updates must be provided in a new SemVer release.

  • Have a version string in SemVer format, for example, <namespace>/<orb>@1.2.3.

  • Can only be published by an owner of the namespace organization.

  • Are published to the CircleCI Orb Registry.

  • Are open source, released under MIT license.

  • Are available via CircleCI CLI.

Development registry orbs

Development registry orbs are temporary, mutable orb tag versions, useful for rapid development and testing prior to deploying a production release.

Development registry orbs:

  • Can only be published if the orb has an initial production version.

  • Are mutable, can be overwritten, and automatically expire 90 days after publication.

  • Have a version string beginning with dev: followed by any string, for example, <namespace>/<orb>@dev:my-feature-branch.

  • Can be published by any member of the namespace organization.

  • Are open source, released under the MIT license.

  • Are available via the CircleCI CLI if the development tag name is known.

Private registry orbs vs. public registry orbs

This section applies to registry orbs only. Inline orbs are inherently private to the project. URL orbs are controlled by your organization’s allow-list and hosting access.

Registry orbs can be published as public or private:

  • If you prefer to publish your registry orb so that only those within your organization can see and use it, you should publish a private registry orb.

  • If you want to publish your registry orb to the CircleCI Orb Registry for use by anyone, create a public registry orb.

Private registry orbs are described in more detail below.

Private registry orbs

An unlimited amount of private registry orbs are available on all of CircleCI’s plans. Using a private registry orb enables you to author an orb while ensuring the following:

  • Your orb will not appear in the CircleCI Orb Registry unless you have the direct URL and are authenticated with the org that created it.

  • 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 registry orb instead of a public registry orb, you also need to understand certain inherent limitations, which include:

  • You will be unable to use the circleci config validate command to validate your configuration. You may, however, use one of the following options:

    • Paste the content of the orb into the orbs stanza of your configuration.

    • Use the circleci config validate --org-id <your-org-id> <path/to/config.yml> command to validate your configuration.

  • You cannot use private registry 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 registry orb from your configuration file, but not from another orb.

Authoring registry orbs

Both public and private registry orbs can be authored in two ways:

For authoring URL orbs, see Create, Test, and Use URL Orbs. For authoring inline orbs, see Create an Inline Orb.

Orb packing (registry orbs only)

Registry orbs are singular YAML files, typically named orb.yml. However, for development, it is often easier to break the code up into more manageable chunks. The circleci orb pack command, a component of the Orb Development Kit, is used to "pack" or condense the separate YAML files together.

If you are using the orb development kit, orb packing is handled automatically by the included CI/CD pipeline, with the orb-tools/pack job.
Orb Project Structure
type name

Directory

commands

Directory

examples

Directory

executors

Directory

jobs

File

@orb.yml

In order to pack an orb, an @orb.yml file must be present. The @ signifies the root of our orb project. See the Create, Test, and Publish a Registry Orb guide for more information. Within the same directory, you can include additional directories for each orb component’s type, such as:

Any additional files or folders will be safely ignored.

Additionally, the pack command provides a special pre-processor for orb developers that allows you to import code from external files using the File include syntax (<<include(file)>>).

CLI command

circleci orb pack <dir> > orb.yml

For orb development kit users, this step is handled automatically.

File include syntax

The <<include(dir/file)>> syntax is a special key for use with the circleci orb pack command and will not work more widely on CircleCI.

The file include syntax (<<include(dir/file)>>) is a special config enhancement. It allows you to import the contents of a file in place as the value for any key within a CircleCI orb configuration file.

When circleci orb pack <dir> > orb.yml is run against a directory containing an @orb.yml file, the pack command begins to combine the contents of the files into a single orb.yml file. During the packing process, each instance of the <<include(dir/file)>> value will be replaced by the contents of the file referenced within.

Included files are always referenced from the relative location of the @orb.yml file.

  • Command-YAML

  • file-sh

  • Packed Command-YAML

description: A simple command that imports from a file when packed.
steps:
  - run:
      name: Hello Greeting
      command: <<include(scripts/file.sh)>>
# This is a bash file, but could really be any text-based file
echo "Hello World"
description: A simple command that imports from a file when packed.
steps:
  - run:
      name: Hello Greeting
      command: |
        # This is a bash file, but could really be any text-based file
        echo "Hello World"

File inclusion is especially useful for separating your configuration’s Bash logic from your YAML. Including Bash scripts will allow you to develop and test your Bash outside of your orb.

View more about including Bash scripts in the Orb Author guide.

Using orbs within your orb and register-time resolution

An orbs stanza can be used inside an orb. Because production orb releases are immutable, the system will resolve all orb dependencies at the time you register your orb rather than at the time you run your build.

For example, orb foo/bar is published at version 1.2.3 with an orbs stanza that imports biz/baz@volatile. At the time you register foo/bar@1.2.3 the system will resolve biz/baz@volatile as the latest version and include its elements directly into the packaged version of foo/bar@1.2.3.

If biz/baz is updated to 3.0.0, anyone using foo/bar@1.2.3 will not see the change from biz/baz@3.0.0 until foo/bar is published at a higher version than 1.2.3.

Orb elements may be composed directly with elements of other orbs. For example, you may have an orb that looks like the example below.

version: 2.1
orbs:
  some-orb: some-ns/some-orb@volatile
executors:
  my-executor: some-orb/their-executor
commands:
  my-command: some-orb/their-command
jobs:
  my-job: some-orb/their-job
  another-job:
    executor: my-executor
    steps:
      - my-command:
          param1: "hello"

See also