Orb Author FAQ
This document describes various questions and technical issues that you may find helpful when authoring orbs.
- Errors Claiming Namespace Or Publishing Orbs
- Secure API Tokens
- Environment Variables
- Supported Programming Languages
- See Also
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 may only claim a single namespace. In order to claim a namespace for an organization the authenticating user must possess owner/admin privileges over the organization.
If you do not have the proper permissions you may 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 our Orbs Quickstart.
Secure API Tokens
Question: How do I protect a user’s API tokens and other sensitive information?
Answer: Utilize the
env_var_nameparameter type for the API key parameter. This parameter type will only accept valid POSIX environment variable name strings as valid input. In the parameter description it is best 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. In either event instruct the user where they can obtain their API key.
Consider validating required environment variables. See more.
Supported Programming Languages
- Question: What language do I use to write an orb?
- Answer: Orbs are packages of CircleCI YAML config language.
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 be (and should) easily written directly using the native run command. The default shell on MacOS and Linux will be Bash.
Interactive Interpreter (Ex: Python)
In some use-cases an Orb may 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. We can utilize 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 when 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 when possible.
Ex: 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)
- 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.
- Refer to Configuration Cookbook for more detailed information about how you can use CircleCI orb recipes in your configurations.