Start Building for Free

Orbs Authoring Best Practices

6 months ago5 min read
Server v4.x
Server v3.x
On This Page


Give your orb a descriptive name

An orb “slug” is made up of a namespace and orb name separated by a forward slash. The namespace represents, the individual, company, or organization that owns and maintains the orb, while the orb name itself should describe the product, service, or action provided by the individual orb.

Proper Orb SlugBad Orb Slug

Categorize your orb

Categorizing your orb allows it to be searchable on the Orb Registry by category. To see how you can categorize your orb using the CircleCI CLI, refer to the relevant section in the Orb Authoring Process guide.

Ensure all orb components include descriptions

Commands, Jobs, Executors, Examples, and Parameters can all accepts descriptions. Ensure each and every component of your orb has a helpful description and provides any additional documentation that may be needed.

description: "Utilize this command to echo Hello to a step in the UI."
  - run:
      name: "Running Echo command"
      command: echo "Hello"

Create detailed descriptions that fully explain the benefit and usage of the orb element. Descriptions are an excellent place for more specific documentation related to each component.

Ensure your orb-publishing context is restricted

If using the Orb Developer Kit, your CircleCI Personal Access Token is saved to a context in your Organization. Ensure you restrict this context so that jobs accessing it will only run when triggered or approved by you or other approved users. For more information, see the Using Contexts guide.



The @orb.yml file acts as the “root” of our project and contains much of the meta-data for our orb, which will appear on the Orb Registry as well as the CLI.

All orbs should include a description

When orbs are published to the Orb Registry they are searchable by their name and description. Besides giving your users a better idea of the purpose and functionality of your orb, good descriptions are important for search optimization.

Orbs utilize a special config key display that can hold a source_url for linking to your Git repository, which in turn holds the orb source code and home_url to link to the product or service home page if applicable.

  home_url: ""
  source_url: ""


Most orbs will contain at least one command

Most orbs will contain at least a single command. Commands are used to execute shell commands and special CircleCI steps automatically on the user’s behalf. In less common situations, for instance, if a tool requires the use of a particular Docker container, an orb may not contain commands and only provide jobs.

Use the minimal number of steps required.

When writing a Reusable Command for your orb, you may input any number of steps. Each step should be properly named as it will appear in the user’s UI. To limit the amount of “noise” in the UI, attempt to use as few steps as possible.

Check for root

Before adding “sudo” to your commands, check to see if the user is already the root user. This can be done dynamically with environment variables.

if [[ $EUID == 0 ]]; then export SUDO=""; else # Check if we are root
  export SUDO="sudo";

$SUDO do_command


Consider “pass-through” parameters

Inside your job, if you are utilizing any commands or executors, you must include a copy of each parameter from each of those components into your job. You can then “pass-through” the parameters given to the job, to each referenced component.

For example, here is a partial snippet of the Node orb’s test job:

As you can see, this job utilizes an executor named default which accepts a version parameter. In order to enable the user of this job to set the version parameter in the executor, we must create the parameter in our job, and pass the parameter to our other orb components.

A docker image parameter might be preferable to an executor

Does your orb have multiple jobs which require a specific execution environment? If so, you may choose to implement a custom executor. Will your job run on most linux platforms? Consider just using the docker executor directly in your job, and parameterize the image.

Consider post and pre steps, and step parameters

Jobs on CircleCI can have steps injected into them, either before or after the job, or somewhere in-between with the use of parameters. Jobs are often easier to set up for users than assembling commands into a custom job (where applicable). Injectable steps allow for more flexibility in jobs and may allow new functionalities in your orb.

See the following:


Orbs do not always require an executor

In orb development, executors are often used to either provide or utilize a specific execution environment when we have multiple jobs which can only run in that environment. For example, if your orb relies on a specific Docker container and includes two jobs and no commands, it makes sense to abstract the execution environment into a single Reusable Executor to be used for both jobs.

Executors are especially useful outside of orbs, as a way to create matrix tests for custom jobs.


Orb Usage Examples provide an excellent way for orb developers to share use-cases and best practices with the community. Usage examples act as the main source of documentation users will reference when utilizing an orb, so it is important to include clear and useful examples.

Be sure to name your usage examples so they reflect the use-case they demonstrate.

Good Usage Example NamesBad Usage Example Names

All public orbs should contain at least one usage example.

Orbs intended for consumption by other organizations should include at least one usage example, with a description.

Use-case based examples

Each included usage example should be named for a specific use-case to instruct the user in how to accomplish a task. Example: install_cli_and_deploy, scan_docker_container, or test_application_with_this-tool

Show correct orb version

Each usage example must present a full example including showing the orb being imported. The version number displayed in the usage-example should match the currently published orb. If your orb is currently on version 0.1.0, and you were to open a pull request to publish version 1.0.0, your usage examples should be updated to reflect version 1.0.0 of the orb in use.


Secrets should never be directly entered

Any information that could be considered “secret” such as API keys, auth tokens and passwords, should never be entered directly as parameter values. Instead, the orb developer should use the env_var_name parameter type, which expects the string value of the name of the environment variable that contains the secret information.

Parameterize the installation path

When installing any binary into a potentially unknown user-defined Docker image, it is hard to know what permissions will be available. Create an install-path parameter, ideally with a default value of /usr/local/bin, and install binaries to this location (if possible). This often avoids the issue of requiring “root” privileges in environments where that may not possible.


Always follow strict semantic versioning

Semantic versioning is a critical update and release practice in which version numbers communicate either bug fixes and patches, new functionality, or breaking changes. Introducing a breaking change as a patch update, for example, can lead to users of that orb automatically receiving updates that block their CI process. Before updating your orbs, make sure you have read over and understood semantic versioning.

Keep a changelog

Keeping a concise changelog allows users of an orb to quickly see what has changed in a particular version. While git does provide a log of changes, it can be difficult to discover the difference between two versions, especially when commits don’t necessarily align to a release. Changelogs should conform to the Keep a Changelog guidelines.


Share your orb with the community!

Have you published an orb to the Orb Registry? We’d love to hear about it. Come make a post on CircleCI Discuss.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.