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 commands: echo: steps: - run: echo "hello world" jobs: hello: machine: true steps: - echo
Note that the example Orb shown above has a single command name
echo and a single job named
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
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.
/ character is used as the scope delimiter. For instance:
foo/barwould look for
barwould look for
barin the local configuration scope.