Automating CIRCLECI ORB Updates

Automating CIRCLECI ORB Updates

CircleCI recently launched Orbs, “a package manager for software delivery automation”. Here we will describe to you how to use Renovate to keep your Orb definitions up-to-date.


Finding Orbs

If you haven’t already started with Orbs, browse to the Orb Registry:

Using Orbs

Next, add an Orb’s definition to your .circleci/config.yml file.

Like any good package registry, each Orb is versioned, e.g. like:


Orb Versioning

If you like a little danger in your software delivery, you can use the volatile tag to mean “give me the latest version”, and every time the Orb runs it will use the latest version even if it’s a non-backwards compatible major update compared to the last time you ran it. Doesn’t seem like a good idea in most cases.

Alternatively you could use a range as version, like cypress-io/cypress@1 which means: “it’s OK to use whatever is the latest 1.x version” and rely on the author retaining semver compatibility and also doesn’t introduce any new features you find unexpected.

Finally, you can “pin” to an exact version for maximum predictability, e.g. cypress-io/cypress@1.1.0.

Getting Updates to Orb Versions

Until now, you had three choices for getting Orb updates:

  • Use the high-risk volatile tag and take any update that comes
  • Use a medium-risk “range” and assume the Orb author honors semver compatibility
  • Pin to an exact version for low risk, and make updates manually

Now with Renovate you have another option: use a low-risk exact version, and receive automated updates whenever a new version is released.

Using Renovate to update CircleCI Orbs

Renovate automatically detects CircleCI configuration files and parses them to detect dependencies, including Orbs and Docker images.

When an Orb definition is found, Renovate can do different things depending on your current version:

  • if you have defined your Orb as volatile, then Renovate skips over it
  • if you have defined your Orb with a “range”, then Renovate creates a PR to “pin” it (e.g. from cypress-io/cypress@1 to cypress-io/cypress@1.2.0)
  • If you have defined an exact version, then Renovate checks if there are any updates for it on the Orb registry and proposes a PR if so (e.g. from cypress-io/cypress@1.1.0 to cypress-io/cypress@1.2.0)

Here is an example of Renovate updating the Cypress Orb from v1.1.0 to v1.2.0:


If you view the diff, you can see the simple yet useful change that’s been made automatically:

Viewing Changelogs

If the Orb has been published with a home URL pointing to a GitHub repository, or the source has been added to Renovate manually, then Renovate will locate and extract the relevant release notes to embed them in the PR, so that you can see what’s changed:

Installing Renovate

If you are a or users, then you can install the Renovate app to use it as a service.

If you use GitHub Enterprise, self-hosted GitLab CE/EE, or Bitbucket Cloud, then you can use the free Renovate OSS CLI tool, e.g. cron’d hourly.

For GitHub Enterprise and GitLab CE/EE, there is also a commercial Renovate Pro product available.

Wrapping Up

  1. Reference CircleCI Orbs in your CircleCI config with an exact version
  2. Use Renovate to receive Pull Requests whenever Orbs are updated

For more details on Renovate, check out the open source project here.


We’d like to thank Hutson Betts for suggesting this feature. If you build and publish libraries, you should check out his Library Release Workflows Orb too.

Rhys Arkins / About Author

Rhys Arkins is Vice President of Product Management, responsible for developer solutions at Mend. He was the founder of Renovate Bot – an automated tool for software dependency updating, which was acquired by Mend in 2019. Rhys is particularly fond of automation and a firm believer in never sending humans to do a machine’s job.