Orbs Authoring Best Practices

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.

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.

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."
steps:
  - 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.

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.

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.

display:
  home_url: "https://www.website.com/docs"
  source_url: "https://www.github.com/EXAMPLE_ORG/EXAMPLE_PROJECT"

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.

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.

description: "A demo of a command to install a CLI, authenticate, and deploy an app"
parameters:
  api-token:
    type: env_var_name
    default: MY_SECRET_TOKEN
steps:
  - run:
      name: "Deploying application"
      command: |
        pip install example
        example login $<<parameters.api-token>>
        example deploy my-app

description: "A bad example of a deploy command. Steps should be named, and combined when possible."
parameters:
  api-token:
    type: env_var_name
    default: MY_SECRET_TOKEN
steps:
  - run: pip install example
  - run: example login $<<parameters.api-token>>
  - run: example deploy my-app

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";
fi

$SUDO do_command

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:

description: |
  Simple drop-in job to test your NodeJS application automatically.
parameters:
  version:
    default: 13.11.0
    description: >
      A full version tag must be specified. Example: "13.11.0" For a full list
      of releases, see the following: https://nodejs.org/en/download/releases
    type: string
executor:
  name: default
  tag: << parameters.version >>

description: >
  Select the version of NodeJS to use. Uses CircleCI's highly cached convenience
  images built for CI.

  Any available tag from this list can be used:
  https://circleci.com/developer/images/image/cimg/node
docker:
  - image: 'cimg/node:<<parameters.tag>>'
parameters:
  tag:
    default: '13.11'
    description: >
      Pick a specific cimg/node image version tag:
      https://circleci.com/developer/images/image/cimg/node
    type: string

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.

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.

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:

• Pre and Post Steps
• Step Parameter

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.

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

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

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.

Any information that could be considered “secret” such as API keys, auth tokens, and passwords, should never be entered directly as a parameter value. Instead, use the env_var_name parameter type, which expects the string value of the name of the environment variable that contains the secret information. The env_var_name parameter type will fail validation if the parameter value is not a POSIX-compliant environment variable name. This is designed to assist in preventing users from accidentally entering the secret value directly as a string.

If your orb requires an “API key”, you should create a parameter named api_key of type env_var_name. The developer using your orb would then pass the name of the environment variable containing the API key as the value of the api_key parameter.

parameters:
  api_key:
    type: env_var_name
    default: API_KEY # An environment variable named API_KEY contains the API key
steps:
  - run:
      environment:
        PARAM_API_KEY: << parameters.api_key >>
      command: |
        # Use the API key

In this example, the string value of API_KEY is saved in the environment variable PARAM_API_KEY. In order to get the value of the environment variable with the name API_KEY, you must evaluate with BASH parameter expansion.

steps:
  - run:
      environment:
        PARAM_API_KEY: << parameters.api_key >>
      command: |
        API_KEY_VALUE=${!PARAM_API_KEY}

When creating a parameter that accepts a non-secret string value, it is often useful to also accept an environment variable that could be reused in multiple places. For example, setting your AWS_REGION is likely not a secret in the traditional sense, you may want to manually enter a region, or override a default value directly. It may also be easier to reference an environment variable that contains the region, for example, if you were using a context to store your AWS metadata for multiple projects.

CircleCI ships with the envsubst CLI built in, which allows us to evaluate environment variables in strings.

parameters:
  region:
    type: string
    default: $REGION # This value is expected to be a string, but may evaluate to an environment variable
steps:
  - run:
      environment:
        REGION: 'us-west-2'
        PARAM_REGION: << parameters.region >>
      command: <<include(script/your_script.sh)>>

When building orbs, it is typical to write your code in a separate file to avoid some of the pitfalls of YAML, as well as gaining access to syntax highlighting and other features in your IDE. In this example, we are including a script named your_script.sh which contains the following code:

REGION_VALUE=$(circleci env subst "$PARAM_REGION")
echo "Expect REGION_VALUE to be us-west-2: $REGION_VALUE"

Going through this substitution process allows us to accept a string value, or an environment variable, and use it in our script. Keep in mind, it is recommended to use the env_var_name parameter type for secrets which should never be entered directly.

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.

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.

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.

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