Search Results for ""

Orbs Best Practices

Orb Best Practices Guidelines

A collection 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.
  • Include the code repo link in the orb description.
  • Include link to website in description.
  • 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 example.
  • Show orb version as x.y (patch version may not need to be included).
  • 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.
  • Example(s) should demonstrate common use case scenerios.


  • 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 existance of required parameters, environment variables or other dependancies 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.


  • 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 a “default” executor.
  • 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.



  • 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