Orb Author FAQ
On This Page
This document describes various questions and technical issues that you may find helpful when authoring orbs.
Errors claiming namespace or publishing orbs
Question: I receive an error when attempting to claim a namespace or publish a production orb.
Answer: You may not be an organization owner/admin.
Organizations can only claim a single namespace. In order to claim a namespace for an organization the authenticating user must have owner/admin privileges within the organization.
If you do not have the required permission level you might see an error similar to below:
Error: Unable to find organization YOUR_ORG_NAME of vcs-type GITHUB: Must have member permission.: the organization 'YOUR_ORG_NAME' under 'GITHUB' VCS-type does not exist. Did you misspell the organization or VCS?
Read more in the Orb CLI Permissions Matrix.
Question: Is it possible to delete an orb I’ve created?
Answer: No. Orbs are public by default and immutable, once a version of an orb is published it can not be changed. This is done 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]
orb sourceCircleCI CLI command does not work for any Private Orbs, regardless if they are listed or unlisted. So 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, please create a Support Ticket.
Secure API tokens
Question: How do I protect a user’s API tokens and other sensitive information?
Answer: Use the
env_var_nameparameter 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.
Question: How can I require a user to add an environment variable?
Answer: 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.
Supported programming languages
Question: What language do I use to write an orb?
Answer: Orbs are packages of CircleCI YAML configuration.
CircleCI orbs package CircleCI reusable config, such as commands, which can execute within a given executor defined by either, the user if using a command within a custom job, or by the orb author if using a reusable job. The environment within which your logic is running may influence your language decisions.
Question: What programming languages can I write my Command logic in?
Answer: POSIX compliant bash is the most portable and universal language. This 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 is the preferred language as it is most commonly available among all available executors. Bash can (and should) be easily written directly using the native run command. The default shell on MacOS and Linux will be bash.
Interactive Interpreter (for example, Python)
For some use-cases an orb might only exist in a particular environment. For instance, if your orb is for a popular Python utility it may be reasonable to require Python as a dependency of your orb. Consider utilizing the run command with a modified shell parameter.
steps: - run: shell: /usr/bin/python3 command: | place = "World" print("Hello " + place + "!")
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)
Command vs Job
Question: Should I create a command or a job?
Answer: 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 select a certain execution platform that is known, such as python, and automatically checkout the users code, install a CLI, and run a deployment command, all with little to no additional configuration required from the user.
- Refer to Orbs Best Practices for suggestions on creating a production-ready orb.
- Refer to Orbs Concepts for high-level information about CircleCI orbs.
- Refer to Orb Publishing Process for information about orbs that you may use in your workflows and jobs.
- Refer to Orbs Reference for examples of reusable orbs, commands, parameters, and executors.
- Refer to Orb Testing Methodologies for information on how to test orbs you have created.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guidefirst).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.