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.
If you haven’t already started with Orbs, browse to the Orb Registry:
Next, add an Orb’s definition to your
Like any good package registry, each Orb is versioned, e.g. like:
cypress-io/cypress@volatile cypress-io/cypress@1 firstname.lastname@example.org email@example.com
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.
Getting Updates to Orb Versions
Until now, you had three choices for getting Orb updates:
- Use the high-risk
volatiletag 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
- 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
Here is an example of Renovate updating the Cypress Orb from
If you view the diff, you can see the simple yet useful change that’s been made automatically:
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:
If you are a github.com or gitlab.com 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.
- Reference CircleCI Orbs in your CircleCI config with an exact version
- 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.