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 publicly on the Orb Registry.
Orb development kit
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 the following section. You can find a simplified version of the publishing process in the README.md file that was generated by the circleci orb init
command at the start of the authoring process.
Issue a new release
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, just ensure any new features, bug fixes, or patches, are created in a non-default branch for your repository. Once you have added or updated your code and are ready to issue a release, continue with these steps.
-
Open a new Pull Request to the default branch.
New releases are only published on merges to the default branch. The included.circleci/config.yml
configuration file automatically packs, tests, and publishes your orbs. By default, both integration tests and unit tests are enabled for this CI pipeline. It is highly recommended that you add integration tests at a minimum to ensure the functionality of your orb. If your orb does not make use of scripts or you do not wish to add unit testing at this time, the bats/run job can be commented out. -
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 on CircleCI.com. -
Title Pull Request with Special Semver Tag.
The included CI config uses the orb-tools orb to automatically publish orbs that pass testing on the default branch, provided that the commit message contains the correct tag designated the intended semver release.
The tag template looks like this:[semver:<increment>]
, where<increment>
is replaced with one of the following values:Increment Description major Issue a 1.0.0 incremented release minor Issue a x.1.0 incremented release patch Issue a x.x.1 incremented release skip Do not issue a release For example, to release the first major public version of your orb from the
alpha
branch, your pull request may be titled[semver:major] first orb release.
-
“Squash” Merge.
Performing a squash merge not only condenses the branch into a single commit when merging into the default branch, but it also keeps the title of the Pull Request as the commit message. -
Complete!
If you head over to the CircleCI app you can view the progress of your orb publishing pipeline. When the pipeline is complete you can search for your orb on the Orb Registry.
Orb publishing process
If you want to dive deeper into the orb development kit and get a look at how the components work together to publish your orb, this section is for you.
The circleci orb init command is responsible for cloning an orb template repository for your orb, including a pre-defined CircleCI configuration file designed with our optimal orb development pipeline.
Included in the /.circleci directory is a README with a breakdown of the included workflows.
Your orb pipeline occurs across two workflows:
test-pack
test-pack
is the first of two workflows to run, and will execute each time code is committed to the repository on any branch.
The test-pack
workflow is responsible for all testing that happens prior to a development version of the orb being published. Integration tests (which happen in the next workflow) can only run once the development version of the orb is available to run the tests on.
A development version of the orb is created in the orb-tools/publish-dev job, and this job requires access to the Personal Access Token, which is secured in a Restricted Context. Using a Restricted Context in this way allows us to store our token as an environment variable such that the job can only be triggered by someone with access to the Context, therefore ‘securing’ the publishing stage.
The workflow runs as follows:
- Tests that do not require special access to the Personal Access Token are run, this stage can run from open source pull requests.
- The workflow is placed on-hold for manual approval.
The workflow will wait for a button click, via an alert prompt in the CircleCI app, before continuing.
- Once the manual approval is authorized, subsequent jobs will be automatically authorized and may access the Restricted Context. This is especially useful when we want to allow open-source pull requests to build against our orb but gives us a chance to ensure there is no malicious code.
-
After the workflow has been approved, the orb-tools/publish-dev job will publish a development version of your orb twice:
Published Development Tag Description <namespace>/<orb>@dev:<branch>
A development tag linked to the branch name. Useful for testing in your configs. <namespace>/<orb>@dev:${CIRCLE_SHA1:0:7}
A development tag specific to this SHA. Used in the following workflow.
You can learn more about the testing jobs in the Orb Testing Methodologies guide.
integration-test_deploy
integration-test_deploy
is the second and last workflow to run in our orb development pipeline. This workflow is automatically triggered, via the API, at the end of the test-pack
workflow. This new workflow has access to the unique development version of the orb that was produced by the test-pack
workflow.
This second stage of the pipeline runs the integration tests, testing the new orb’s functionality that has just been added and published to the development version..
After integration testing, and only on the default branch, the deployment job will run. orb-tools/dev-promote-prod-from-commit-subject is responsible for taking the SHA specific development version of the orb, and promoting it to a semantically versioned public release.
- orb-tools/dev-promote-prod-from-commit-subject:
orb-name: <namespace>/<orb-name>
context: <publishing-context>
add-pr-comment: false
fail-if-semver-not-indicated: true
publish-version-tag: false
requires:
- integration-test-1
filters:
branches:
only: <your default branch>
The fail-if-semver-not-indicated
parameter is set to true by default, ensuring any commits without the proper semver tag in the commit title, result in a failed build.
You can optionally enable additional features such as publishing a version tag back to GitHub, and automatically posting new versions to the pull request via comment.
Publish version tag to GitHub
Your CircleCI orb will ultimately be hosted and displayed on the Orb Registry, however, if you would like to track your releases on GitHub, it is possible to automatically publish a version tag from CircleCI.
To push a tag to GitHub, CircleCI will need a deploy key with write access. Follow the linked docs to generate and add your deploy key. When complete, you will see a “fingerprint” generated "SO:ME:FIN:G:ER:PR:IN:T"
for that key. Add your SSH fingerprint to your orb-tools/dev-promote-prod-from-commit-subject
job via the ssh-fingerprints
parameter.
- orb-tools/dev-promote-prod-from-commit-subject:
publish-version-tag: true
ssh-fingerprints: "SO:ME:FIN:G:ER:PR:IN:T"
You can find a full set of available commands, jobs and parameters for the orb-tools orb on the Orb Registry.