Start Building for Free

Publishing Orbs

1+ year ago2 min read
On This Page

This guide covers the steps required to publish an orb.


After authoring your orb, you can publish it with a semantically versioned tag, and the orb will appear on the Orb Registry.

Orb Publishing Process

If you are publishing your orb using the orb development kit, rather than manually, semantic releases are straight-forward using the steps set out in this section. You can find a simplified version of the publishing process in the file that is generated by the circleci orb init command at the start of the authoring process.

Issue a new release with the orb development kit

The steps below show how to issue a new semantic release of your orb.

Once you have generated your orb sample project with the circleci orb init command, you will have been automatically migrated to the alpha branch. The name of the branch does not matter but it is best practice to make your changes on a non-default branch.

Once you have made your changes, commit them and push them up to your branch. We strongly encourage using Conventional Commits for your commit messages.

Next, follow these steps to create a new release from your changes.

  1. Open a new Pull Request to the default branch.
    The included config.yml and test-deploy.yml files in the ./circleci directory are configured to automatically lint, shellcheck, review, and test your orb changes in the CircleCI web app.

  2. Ensure all tests pass.
    You can view the results of your tests directly on GitHub within the Pull Request, or, for a more detailed view, watch the entire pipeline in the CircleCI web app. Notice there are two workflows, lint-pack will run first and contains our linting, shellchecking, review, and will publish a development version to be tested in the second workflow. The test-deploy workflow contains our integration tests, and can publish the production version of our orb when ready. Orb test results as reported by GitHub Checks API on pull request

  3. “Squash” Merge.
    When your changes are complete, we recommend (not required) “ Squash Merging” your changes into a single commit, with a Conventional Commit Message.


    • fix: x-command parameter from string to integer
    • feat: added new x parameter to y command
  4. Tag and Release!
    Your changes have now been merged to the default branch, but if you check the Orb Registry, you will see no new versions have been published.

To publish a new version of our orb, you need to tag your release. A tag can be created and pushed manually, however we recommend using’s Releases feature.

Using GitHub’s Releases feature will allows you to publish “Release Notes”, which will function as a changelog for your orb.

Follow the GitHub docs to create a new release.

  1. When asked to select a tag, specify the new tag that will be published with this release. Double check the current orb version in the Orb Registry. If you are unsure of what type of change you are making, we will have an opportunity to correct this in a moment. Ensure your tag fits the format vX.Y.Z
  2. Click the “+ Auto-generate release notes” button. A summary of changes will be generated for you, containing any pull requests which have been merged since the last release. If you have used Conventional Commit messages, it should be easy to determine the type of semantic increment change based on the commit message. For instance, if we had two commits that were prefixed with “fix:”, we would expect the semantic version to increment by a “patch” level.
  3. Add your title, and publish the release.
  4. Complete!

After the release is published, a tag will be created and a CircleCI pipline will trigger for a final time. This final pipeline will perform all of the same steps as before with one additional final job, which will create the new orb version and publish it to the Orb Registry.

If you view the final orb-tools/publish job, in the “Publishing Orb Release” step, you will see a message like the following:

Your orb has been published to the CircleCI Orb Registry.
You can view your published orb on the CircleCI Orb Registry at the following link:

You can see this example from the orb-tools orb here

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.

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.