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 fi
- 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.
- 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.