Publishing orbs
This guide covers the steps required to publish an orb.
Introduction
After authoring your orb, you can publish it with a semantically versioned tag, and the orb will appear on the Orb Registry.
| 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 the circleci orb init command generates 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 automatically migrated to the alpha branch. The name of the branch does not matter but best practice is 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.
-
Open a new Pull Request to the default branch.
The included
config.ymlandtest-deploy.ymlfiles in the./circlecidirectory automatically lint, ShellCheck, review, and test your orb changes in the CircleCI web app. -
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-packwill run first and contains our linting, ShellCheck, review, and will publish a development version to be tested in the second workflow. Thetest-deployworkflow contains our integration tests, and can publish the production version of our orb when ready.
-
"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 integerfeat: added new x parameter to y command -
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.
-
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 -
Click the
+ Auto-generate release notesbutton. 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 semantic increment change based on the commit message. For instance, if we had two commits prefixed with "fix:", we would expect the semantic version to increment by a "patch" level. -
Add your title, and publish the release.
-
Complete!
After the release is published, a tag is created and a CircleCI pipeline 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.2You can see this example from the orb-tools orb here