Welcome

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 Publishing Process

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.

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

  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 on CircleCI.com. Orb test results as reported by GitHub Checks API on pull request

  3. 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. First major release of an orb - Pull Request

  4. “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. Squash merge PR, preserving the semver title

  5. 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. Manually approve publishing development orbs 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.