Orbs Concepts

CircleCI orbs are shareable packages of configuration elements, including jobs, commands, and executors. Orbs make writing and customizing CircleCI config simple. The reusable configuration elements used in orbs are explained fully in the Reusable Configuration Reference.

CircleCI’s Reusable Configuration features allow you to define parameterizable configuration elements and re-use those elements throughout a project config file. It is recommended you become familiar with the full Configuration Reference features before moving on to the Reusable Configuration Reference.

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

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 the registry page for the Node Orb.

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.

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, but 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:

# 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>

A namespace is a unique identifier claimed by a user or organization to group a set of orbs by author. Each user or organization can claim one unique and immutable namespace. Each namespace can contain many uniquely named 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, please contact support.

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

Orbs utilize 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]

When you import an orb, you can pin it to a particular semver component.

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.

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

• Production orbs are immutable, they cannot be deleted or edited, and updates must be provided in a new semver release
• Version string must be in semver format, for example, <namespace>/<orb>@1.2.3
• Production orbs can only be published by an owner of the namespace organization
• Published to the Orb Registry
• Open source, released under MIT license
• Available via CircleCI CLI

Development orbs are temporary overwrite-able orb tag versions, useful for rapid development and testing prior to deploying a semver deployed production change.

• Development orbs are mutable, can be overwritten, and automatically expire 90 days after they are published
• Version string must begin with dev: followed by any string, for example, <namespace>/<orb>@dev:my-feature-branch
• Development orbs may be published by any member of the namespace organization
• Will not appear on the Orb Registry
• Open source, released under MIT license.
• Available via CircleCI CLI (if the development tag name is known)

Inline orbs are defined directly within the user’s config, are completely local and scoped to the individual project.

See: Writing Inline Orbs for more information on inline orbs.

• Not published to the orb service
• No versioning
• Exist only locally within the user’s config
• Not accessible outside of the repository
• Not public
• Not accessible via CircleCI CLI

There are two ways to publish an orb: public or private:

• If you prefer to publish your orb so that only those within your organization can see and use it, you should publish a private orb.
• If you want to publish your orb to the CircleCI Orb Registry for use by anyone, create a public orb.

Private orbs are described in more detail below.

An unlimited amount of private orbs are available on all of CircleCI’s plans. Using a private 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 orb instead of a public 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 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.

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

• Using the Manual Orb Authoring Process
• Using the orb development kit (recommended)

All CircleCI 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.

Example: Orb Project Structure

In order to pack an orb, an @orb.yml file must be present. The @ signifies the root of our orb project. Within the same directory, you can include additional directories for each orb component’s type, such as commands, jobs, executors, and examples. 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.

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

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.

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.

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"

• Refer to Orb Introduction for a high-level overview of CircleCI orbs.
• Refer to Orbs Reference for detailed reference information about Orbs, including descriptions of commands, jobs and executors.
• Refer to Orbs FAQs for information on frequent issues encountered when using orbs.