Search Results for ""

Orbs Best Practices

A collection of best practices and strategies for authoring orbs. CircleCI orbs are shareable packages of configuration elements, including jobs, commands, and executors.



  • Ensure all commands, jobs, executors, and parameters have detailed descriptions.
  • Provide a source_url, and if available, home_url via the display key.
  • Define any prerequisites such as obtaining an API key in the description.
  • Be consistent and concise in naming your orb elements. For example, don’t mix “kebab case” and “snake case.”


  • Must have at least 1 usage example.
  • Show orb version as x.y (patch version may not need to be included) in the example.
  • Example should include most common/simplest use case calling a top-level job or other base-case elements if no job is present.
  • If applicable, you may want to showcase the use of pre and post steps in conjunction with an orb’s job.


  • In general, all orbs should contain at least one command.
  • Some exceptions may include creating an orb for the sole task of providing an executor.
  • Combine one or more parameterizable steps to simplify a task.
  • All commands available to the user should complete a full task. Do not create a command for the sole purpose of being a “partial” to another command unless it can be used on its own.
  • It is possible not all CLI commands need to be transformed into an orb command. Single line commands with no parameters do not necessarily need to have an orb command alias.
  • Command descriptions should call out any dependencies or assumptions, particularly if you intend for the command to run outside of a provided executor in your orb.
  • It is a good idea to check for the existence of required parameters, environment variables or other dependencies as a part of your command.


if [ -z "$<<parameters.SECRET_API_KEY>>" ]; then
  echo "Error: The parameter SECRET_API_KEY is empty. Please ensure the environment variable <<parameters.SECRET_API_KEY>> has been added."
  exit 1


  • When possible, use defaults for parameters unless a user input is essential.
  • Utilize the “env_var_name” parameter type to secure API keys, webhook urls or other sensitive data.
  • Injecting steps as a parameter is a useful way to run user defined steps within a job between your orb-defined steps.Good for if you need to perform an action both before and after user-defined tasks - for instance, you could run user-provided steps between your caching logic inside the command.

Installing binaries and tools

  • Set an install-path parameter, ideally with a default value of /usr/local/bin, and ensure to install the binary to this parameterized location. This may often avoid the issue of needing root privileges in environments where the user may not have root.
  • If rootis required for your use case, it is recommended to add pre-flight checks to determine if the user has root permissions and gracefully fail with a descriptive error message alerting the user they need proper permissions.
  • Add the binary to the user’s path via $BASH_ENV so the user may call the binary from a separate run statement. This is required when installing to a non-default path. example:
    echo `export PATH="$PATH:<<parameters.install-path>>"` >> $BASH_ENV


  • Jobs should utilize Commands defined within the orb to orchestrate common use cases for this orb.
  • Plan for flexibility
  • Plan how users might utilize post-steps, pre-steps, or steps as a parameter.
  • Consider creating pass-through parameters.
  • If a job utilizes an executor or command that accepts parameters, the job will need those parameters as well if they are to be passed down to the executor or commands.
  • Never hard-code the executor. Utilize a parameterizable (ex: ‘default’) executor that is able to have the image or tag overwritten.


  • At least one executor per supported OS (MacOs, Windows, Docker, VM).
  • Must include one executor named default.
  • Executor should be parameterized to allow the user to overwrite the version/tag in the event an issue arises with the included image.

Imported Orbs

  • Should import full semver immutable version of orb. This protects your orb from changes to the dependancy orb (like a lock file).
  • [Partner Only] - Should only import Certified/Partnered namespaces, or Orbs of the same namespace.


  • Deploy full CI/CD for your orb with a fully automated build > test > deploy workflow using the Orb Starter Kit (Beta). This handles all of the below.
  • Optional: Utilize a destructured orb pattern to more easily maintain individual orb components.

Sample Data

  • Sample data neccesary for testing your Orb in CI/CD pipelines should be kept as small as possible, e.g a single composer.json or package.json file with minimal dependencies.
  • Sample data should live under the sample/ directory in the orb’s repository, when possible.



  • Utilize semver versioning (x.y.z)
  • Major: Incompatible changes
  • Minor: Add new features (backwards compatible)
  • Patch: Minor bug fixes, metadata updates, or other safe actions.

View our Orb Deployment best practices here: [coming soon]

This section is handled automatically via the Orb Starter Kit.


GitHub has the ability to tag repositories with “topics”. This is used as a datapoint in GitHub search but more importantly, in their Explore page to group repositories by tags. We suggest using the topic circleci-orbs for a repo containing an orb. This allows users to view a listing of orb repos whether they are CircleCI, Partner, or community orbs on this page.

How to add a topic to a GitHub repository