Publishing Orbs

today • 1 min read

Cloud

This guide covers the steps required to publish an orb.

• Introduction
• Issue a new release with the orb development kit

Introduction

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

Note: If your orb is private, it will not be searchable on the Orb Registry. However, the URL will be accessible to authenticated users of the orb.

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 README.md 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.

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.

   Examples:

   • 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 GitHub.com’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:
https://circleci.com/developer/orbs/orb/circleci/orb-tools?version=11.1.2

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.

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