This document describes various questions and technical issues that you may find helpful when working with Orbs.
Downloading, Integrating, and Testing Orbs
Question: How do I download, integrate and test orbs?
Answer: You can invoke orbs using the
orbsstanza in version 2.1 or higher of a CircleCI configuration. For example, if you want to publish an orb called
hello-buildin the namespace
circleciand have a published version
0.0.1, invoke an orb like the example shown below:
orbs: hello: email@example.com
You may then use the elements of that orb in your configuration by referencing these elements under the key
hello. For example, if an orb has a job called
hello-build, you can invoke that job in a workflow like the example shown below.
workflows: info: jobs: - hello/hello-build
CircleCI publishes a web-based registry viewer so orbs documentation can be auto-generated. You can always pull the source of Orbs directly as well. For example, you can run
circleci orb source firstname.lastname@example.org
Build Error When Testing Locally
- Question: Why do I get the following error when testing locally:
circleci build -c .circleci/jobs.yml --job test
Error: You attempted to run a local build with version 2.1 of configuration.
- Answer: To resolve this error, run
circleci config processon your configuration and then save that configuration to disk. You then should run
circleci local executeagainst the processed configuration.
- Question: Why do I get the following error when re-running the same workflow:
only certified orbs are permitted in this project.
- Answer: Try making a whitespace change or similar. Your config won’t recompile until you’ve made a change. Config processing happens before the compiled code is passed into the workflows conductor. Because of that, the workflows conductor (where you trigger the rebuild) knows nothing of the original 2.1 config.
Question: Is there a standard way to to log output? For example, Jenkins plugins provide console links to show the log output and provides hooks to log those messages. It is possible to log to stdout, but is there a better way to log those log messages.
Answer: In CircleCI, all steps that run are logged, so any output from those steps will appear in the console. You can use SSH to
echothings directly. CircleCI does not have a separate logging facility outside the console output.
Question: How can I intentionally fail a job that invokes an orb from within an orb?
Answer: You can always return a non-zero status code from the shell to fail the job. You can also use
run: circleci-agent step halt as a step to exit the job without failing.
- Refer to Orb Introduction, for a high-level overview.
- Refer to Using Orbs, for more about how to use existing orbs.
- Refer to Creating Orbs, where you will find step-by-step instructions on how to create your own orb.
- Refer to Reusing Config for more detailed examples of reusable orbs, commands, parameters, and executors.