Manual Orb Authoring Process
This document is applicable to the following:
This guide covers the steps required to create a simple orb, manually, without using the orb development kit. We recommend the orb development kit for most orb projects, to find out more, see the Orb Authoring Guide.
- If you have not already done so, claim a namespace for your user/organization using the following command, substituting your namespace choice and GitHub org name:
circleci namespace create <my-namespace> github <my-gh-org>
Note: When creating a namespace via the CircleCI CLI, be sure to specify the VCS provider.
- Create your orb inside your namespace. At this stage no orb content is being generated, but the naming is reserved for when the orb is published.
To create a public orb:
circleci orb create <my-namespace>/<my-orb-name>
To create a private orb:
circleci orb create <my-namespace>/<my-orb-name> --private
- Create the content of your orb in a YAML file. Here is a simple example to get you started:
version: 2.1 description: A greeting command orb commands: greet: description: Greet someone with a "hello". parameters: to: type: string default: World steps: - run: echo "Hello, << parameters.to >>"
- Validate your orb code using the CLI:
circleci orb validate /tmp/orb.yml
- Publish a dev version of your orb:
circleci orb publish /tmp/orb.yml <my-namespace>/<my-orb-name>@dev:first
- 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. Using the following command will increment the dev version to become0.0.1
:circleci orb publish promote <my-namespace>/<my-orb-name>@dev:first patch
- Your orb is now published, in an immutable form, as a production version and can be used safely in CircleCI projects. You can pull the source of your orb using:
circleci orb source <my-namespace>/<my-orb-name>@0.0.1
- List your available orbs using the CLI:
To list public orbs:
circleci orb list <my-namespace>
To list private orbs:
circleci orb list <my-namespace> --private
For more information on how to use the circleci orb
command, see the CLI documentation.