Manual Orb Authoring Process

today • 1 min read

Cloud

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.

Create a namespace

1. If you have not already done so, claim a namespace for your user/organization using the following command, substituting your namespace choice and GitHub organization name:

   circleci namespace create <name> --org-id <your-organization-id>
   

Create your orb

1. 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. If you are using CircleCI server, you should ensure the --private flag is used here to keep your orbs private within your installation. 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
   

2. 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

1. Validate your orb code using the CLI:

   circleci orb validate /tmp/orb.yml
   

Publish your orb

1. Publish a dev version of your orb:

   circleci orb publish /tmp/orb.yml <my-namespace>/<my-orb-name>@dev:first
   

2. 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 become 0.0.1:

   circleci orb publish promote <my-namespace>/<my-orb-name>@dev:first patch
   

3. 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 available orbs

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

Next Steps

For more information on how to use the circleci orb command, see the CLI documentation.

---

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 guide first).
• 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.

Need support?

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.