Orbs Concepts

Quick start

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.

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. It is recommended you become familiar with the full Configuration Reference features before moving on to the Reusable Configuration Reference.

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@x.y.z

jobs:
  build:
    docker:
      - image: 'cimg/python:3.6'
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    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

description: >
  Select the version of NodeJS to use. Uses CircleCI's highly cached convenience
  images built for CI.
docker:
  - image: 'cimg/node:<<parameters.tag>>'
    auth:
      username: mydockerhub-user
      password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
parameters:
  tag:
    default: '13.11'
    description: >
      Pick a specific cimg/node image version tag:
      https://hub.docker.com/r/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 >>'
    auth:
      username: mydockerhub-user
      password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
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

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

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 and are displayed, for reference, in the Orb Registry. Below is a sample usage example:

# Source https://github.com/circleci-public/orb-project-template/blob/master/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

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.

Semantic versioning

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]
Semver Description
Major Breaking changes.
Minor Backwards compatible additional features.
Patch Bug fixes.

When you import an 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.

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

Orb versions (development vs production vs inline)

Production orbs

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

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

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

Orb packing

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.

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.

Example: Orb Project Structure

type name
commands
examples
executors
jobs
@orb.yml

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.

File include syntax

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.

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

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

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