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.
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.
Open a new Pull Request to the default branch.
test-deploy.ymlfiles in the
./circlecidirectory are configured to 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, shellchecking, review, and will publish a development version to be tested in the second workflow. The
test-deployworkflow contains our integration tests, and can publish the production version of our orb when ready.
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
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
- 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.
- Add your title, and publish the release.
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.
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.