Fetching contributors…
Cannot retrieve contributors at this time
44 lines (32 sloc) 1.58 KB

Orb structure

Orbs are authored with similar YAML syntax to the base CircleCI build configuration. Each orb also has its own namespace to use when invoking its elements. Orbs are typically packaged as a single file, can also be locally defined inside configs or other orbs. There is support for packing multiple files together for large orbs.

Anatomy of an orb

Orbs are composed of one or more of the following elements, each of which represents a type of invocable element in CircleCI project configuration:

Additionally, usage examples may also be provided for documentation purposes.

An example orb:

# foo orb
description: A hello-world orb example
      - run: echo "hello world"
    machine: true
      - echo

Note that the example Orb shown above has a single command name echo and a single job named hello.


Orb, command, job, executor, and parameter names can only contain lowercase letters a-z, digits, and _ and -, and must start with a letter.

Scoping considerations in orb invocation

An orb foo effectively has a namespace called foo for use in your build configuration, and everything directly inside an orb is considered local to that orb.

The / character is used as the scope delimiter. For instance:

  • foo/bar would look for bar in the foo orb.
  • bar would look for bar in the local configuration scope.