Orb Authoring Process
Once you have configured your platform to work with CircleCI orbs, you are ready to begin authoring your own orb. CircleCI has attempted to make this process simple and easy, eliminating any potential confusion by enabling you to use inline templates and other pre-configured templates to quickly author a new orb. The sections below describe the process of authoring your own orb.
Before you create your first orb, please see the following notes:
- Orbs exist in namespaces.
- Each organization or username can claim one unique namespace, and namespaces cannot be deleted.
- Namespaces are global within the CircleCI orb registry, so pick a unique name!
- Only users with “owner”/”administrator” privileges within a given GitHub/Bitbucket organization can create a namespace linked to that organization.
- Once an orb has been created by an org admin, any org member can publish
devorbs. When ready,
devorbs can be promoted into production by org admins.
- When stored as a project environment variable or Contexts resource, an API token generated by an org admin can help automate the orb publishing process, enabling any org member to potentially publish a production orb by using the CircleCI CLI in a CircleCI job.
- To use the orbs you create, you will need to enable the “Allow Uncertified Orbs” setting in the Security section of CircleCI’s Organization Settings page for your organization (
- If you are creating an orb, you can use development versions to avoid having your orb publicly/permanently listed in CircleCI’s orb registry before it is ready.
The following high-level steps are needed to publish your first orb:
1) Claim a namespace (assuming you don’t yet have one). For example:
circleci namespace create sandbox github CircleCI-Public
In this example we are creating the
sandbox namespace, which will be linked to the GitHub organization
Note: When creating a namespace via the CircleCI CLI, be sure to specify the VCS provider.
2) Create the orb inside your namespace. This doesn’t generate any content, but rather reserves the naming for when the orb is published. For example:
circleci orb create sandbox/hello-world
3) Create the content of your orb in a file. You will generally do this in your code editor in a git repo made for your orb, but, for the sake of an example, let’s assume a file in
/tmp/orb.yml could be made with a bare-bones orb like:
echo 'version: "2.1"\ndescription: "a sample orb"' > /tmp/orb.yml
4) Validate that your code is a valid orb using the CLI. For example, using the path above you could use:
circleci orb validate /tmp/orb.yml
5) Publish a dev version of your orb. Assuming the above orb, it would look like this:
circleci orb publish /tmp/orb.yml sandbox/hello-world@dev:first
6) Once you are ready to push your orb to production, you can publish it manually using
circleci orb publish or promote it directly from the dev version. In the case where you want to publish the orb, assuming you wanted to increment the new dev version to become 0.0.1, you can use:
circleci orb publish promote sandbox/hello-world@dev:first patch
7) Your orb is now published in an immutable form as a production version and can be used safely in builds. You can then pull the source of your orb using:
circleci orb source firstname.lastname@example.org
When designing your own orbs, make sure your orbs meet the following requirements:
- Orbs should always use
description. - Be sure to explain usage, assumptions, and any tricks in the
descriptionkey under jobs, commands, executors, and parameters.
- Match commands to executors - If you are providing commands, try to provide one or more executors in which they will run.
- Use concise naming for your orb - Remember that use of your commands and jobs is always contextual to your orb, so you can use general names like “run-tests” in most cases.
- Required vs. optional parameters - Provide sound default values of parameters whenever possible.
- Avoid job-only orbs - Job-only orbs are inflexible. While these orbs are sometimes appropriate, it can be frustrating for users to be unable to use the commands in their own jobs. Pre and post steps when invoking jobs are a workaround for users.
stepsare powerful - Wrapping steps provided by the user allows you to encapsulate and sugar things like caching strategies and other more complex tasks, providing a lot of value to users.
Refer to Reusing Config for details and examples of commands, executors and parameters in orbs.
When developing your own orb, you may find it useful to write an inline orb. The section below describes how you can write your own inline orb.
Writing Inline Orbs
Inline orbs can be handy during development of an orb or as a convenience for name-spacing jobs and commands in lengthy configurations, particularly if you later intend to share the orb with others.
To write inline orbs, place the orb elements under that orb’s key in the
orbs declaration in the configuration. For example, if you want to import one orb and then author inline for another, the orb might look like the example shown below:
version: 2.1 description: # The purpose of this orb orbs: my-orb: orbs: codecov: email@example.com executors: specialthingsexecutor: docker: - image: circleci/ruby:2.7.0 commands: dospecialthings: steps: - run: echo "We will now do special things" jobs: myjob: executor: specialthingsexecutor steps: - dospecialthings - codecov/upload: path: ~/tmp/results.xml workflows: main: jobs: - my-orb/myjob
In the example above, note that the contents of
my-orb are resolved as an inline orb because the contents of
my-orb are a map; whereas the contents of
codecov are a scalar value, and thus assumed to be an orb URI.
Example Inline Template
When you want to author an orb, you may wish to use this example template to quickly and easily create a new orb with all of the required components. This example includes each of the three top-level concepts of orbs. While any orb can be equally expressed as an inline orb definition, it will generally be simpler to iterate on an inline orb and use
circleci config process .circleci/config.yml to check whether your orb usage matches your expectation.
version: 2.1 description: This is an inline job orbs: inline_example: jobs: my_inline_job: parameters: greeting_name: description: # a helpful description type: string default: olleh executor: my_inline_executor steps: - my_inline_command: greeting_name: <<parameters.greeting_name>> commands: my_inline_command: parameters: greeting_name: type: string steps: - run: echo "hello <<parameters.greeting_name>>, from the inline command" executors: my_inline_executor: parameters: version: type: string default: "2.4" docker: - image: circleci/ruby:<<parameters.version>> workflows: build-test-deploy: jobs: - inline_example/my_inline_job: name: mybuild # best practice is to name each orb job - inline_example/my_inline_job: name: mybuild2 greeting_name: world
Describing your Orb
Before publishing your orb, it is recommended you add metadata to your orb to aid in the discoverability and documentation of your orb. We recommend adding a top-level
description that informs users of the purpose of your orb and is indexed in search.
display key, add a link to the git repository via the
source_url. If your orb relates to a specific product or service, you may optionally include a link to the homepage or documentation for said product or service via the
version: 2.1 description: > Integrate Amazon AWS S3 with your CircleCI CI/CD pipeline easily with the aws-s3 orb. display: home_url: https://aws.amazon.com/s3/ source_url: https://github.com/CircleCI-Public/aws-s3-orb
description and contents of the
display key will be featured in the header of the orb’s registry page.
Providing Usage Examples of Orbs
examples stanza is available in configuration version 2.1 and later
As an author of an orb, you may wish to document examples of using it in a CircleCI configuration file, not only to provide a starting point for new users, but also to demonstrate more complicated use cases.
When you have completed authoring an orb, and have published the orb, the orb will be published in the Orb Registry. You will see your newly-created orb in the Orb Registry, which is shown below.
Below is an example orb you can use:
version: 2.1 description: A foo orb commands: hello: description: Greet the user politely parameters: username: type: string description: A name of the user to greet steps: - run: "echo Hello << parameters.username >>"
If you would like, you may also supply an additional
examples stanza in the orb like the example shown below:
version: 2.1 examples: simple_greeting: description: Greeting a user named Anna usage: version: 2.1 orbs: foo: firstname.lastname@example.org jobs: build: machine: true steps: - foo/hello: username: "Anna"
Please note that
examples can contain multiple keys at the same level as
simple_greeting, allowing for multiple examples.
Expected Usage Results
The above usage example can be optionally supplemented with a
result key, demonstrating what the configuration will look like after expanding the orb with its parameters:
version: 2.1 examples: simple_greeting: description: Greeting a user named Anna usage: version: 2.1 orbs: foo: email@example.com jobs: build: machine: true steps: - foo/hello: username: "Anna" result: version: 2.1 jobs: build: machine: true steps: - run: command: echo Hello Anna workflows: version: 2 workflow: jobs: - build
Usage Examples Syntax
The top level
examples key is optional. Usage example maps nested below it can have the following keys:
- description: (optional) A string that explains the example’s purpose, making it easier for users to understand it.
- usage: (required) A full, valid config map that includes an example of using the orb.
- result: (optional) A full, valid config map demonstrating the result of expanding the orb with supplied parameters.
- Refer to Validate and Publish Your Orb for next steps.