Orb author FAQ

20 days ago

Cloud Server v4+

This document describes various questions and technical issues that you may find helpful when authoring orbs.

FAQs

Which orb type should I author?

The type of orb you should author depends on what you need it for and how you want to share it.

Registry orbs: Best for public sharing or when you need semantic versioning.
URL orbs: Best for sharing across your organization but not externally. Requires hosting and administrative allow-list management.
Inline orbs: Best for project-specific reusable configuration and testing before extracting config into a URL or registry orb. No publishing required, defined directly in your config file.

See Choosing an Orb Type for detailed guidance.

Is it possible to delete a registry orb that I have created?

No. Registry orbs are public by default and immutable, once a version of a registry orb is published it can not be changed. Registry orbs are immutable by design so users can reasonably expect a known version of an orb will behave the same on every run. Deleting an orb could potentially lead to a failing pipeline in any of its user’s projects.

Orbs can however be "Unlisted" from the Orb registry. Unlisted orbs still exist and are discoverable via the API or CLI, but will not appear in the Orb Registry results. This may be desired if for instance, an orb is no longer maintained.

circleci orb unlist <namespace>/<orb> <true|false> [flags]

Use caution when using private orbs. Currently the orb source CircleCI CLI command does not work for any private orbs, regardless if they are listed or unlisted. Unless the private orb name is documented before it is unlisted, you will not be able to find the orb through the orb registry or the CircleCI CLI. If you believe this happened to you, you can create a support ticket.

How do I protect a user’s API tokens and other sensitive information?

Use the env_var_name parameter type for the API key parameter. This parameter type will only accept valid POSIX environment variable name strings as input. In the parameter description, it is best practice to mention to the user to add this environment variable.

If you are interested in reading more on this topic, visit the Environment Variable Name and Best Practices pages.

How can I require a user to add an environment variable?

Create a parameter for the environment variable name, even if it is a statically named environment variable the user should not change. Then, assign it the correct default value. In the parameter description let the user know if this value should not be changed. Either way, consider instructing the user on how they can obtain their API key.

Consider validating required environment variables. See more in the Orb Author Best Practices guide.

If you are interested in reading more on this topic, visit the Environment Variable Name and Best Practices pages.

What language do I use to write an orb?

Orbs are packages of CircleCI YAML Configuration.

CircleCI orbs package Reusable Configuration Elements like Commands. These commands run within an Executor—either one the user specifies in a custom job, or one the orb author defines in a Reusable Job. This execution environment may influence your language decisions.

What programming languages can I write my Command logic in?

POSIX compliant Bash is the most portable and universal language. Bash is the recommended option when you intend to share your orb. Orbs do, however, come with the flexibility and freedom to run other programming languages or tools.

Bash

Bash is the preferred language as it is most commonly available among all available executors. Bash should be written directly using the native Run command. The default shell on macOS and Linux will be Bash.

Ruby

steps:
  - run:
    name: Check Ruby shell
    shell: ruby
    command: puts 'hi'

Node

steps:
  - run:
    name: Check Node shell
    shell: node
    command: console.log('node')

Python

steps:
  - run:
    name: Check Python shell
    shell: python3
    command: print('python')

Binary

This option is strongly discouraged wherever possible. Sometimes it may be necessary to fetch a remote binary file such as a CLI tool. These binaries should be fetched from a package manager or hosted by a VCS such as GitHub releases wherever possible. For example, installing Homebrew as a part of the AWS Serverless orb.

steps:
  - run:
    command: >
      curl -fsSL
      "https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh" | bash
      /home/linuxbrew/.linuxbrew/bin/brew shellenv >> "$BASH_ENV"
    name: Install Homebrew (for Linux)

Should I create a command or a job?

The answer might be both, but it will heavily depend on the task you want to accomplish.

An orb Command can be utilized by the user, or even the orb developer, to perform some action within a job. The command itself has no knowledge of the job it is within as the user could utilize it however they wish. A command may be useful, for example, to automatically install a CLI application or go a step further and install and authenticate.

A Job defines a collection of steps and commands within a specific execution environment. A job is highly opinionated as it generally chooses the execution platform to run on and what steps to run. Jobs may offer a useful way to automate tasks such as deployments. A deployment job may look something like this:

Select a certain execution platform that is known, such as Python.
Automatically checkout the users code.
Install a CLI.
Run a deployment command.

All without requiring any additional configuration from the user.

[path]

[title]