Automating CIRCLECI ORB Updates

Using Orbs

Add an Orb’s definition to your .circleci/config.yml file.

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

cypress-io/cypress@volatile
cypress-io/cypress@1
cypress-io/cypress@1.1
cypress-io/cypress@1.1.0

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)

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.