Articles

Today on a slack, this happened.

AFAIK, GHActions Docker support is “build a docker image from a dockerfile each time”, so you have auditability and a few other things, but you don’t have “very fast reuse”. Whereas CircleCI orbs are Docker images. No rebuilds at invocation time.

Wait, what? Lets read that again.

CircleCI orbs are Docker images.

No, definitely not! Not at all, not even close!

The poster’s comment stemmed from a small discussion about CircleCI from a frustrated user.

Hopefully I can clarify a bit more what an orb is and why you might use it.

The Orb in CircleCI

Orbs are JUST yaml that you inject into your process (your config.yml) - you consume that yaml as jobs or commands or executors (and MAYBE a few other things if you’re deep in the weeds).

CircleCI themselves define it:

A reusable package of YAML configuration that condenses repeated pieces of config into a single line of code.

and

Orbs are reusable snippets of code that help automate repeated processes, accelerate project setup, and make it easy to integrate with third-party tools.

What does this mean to me?

Ok, great - but can we break that down into something that someone who has used a little bit of CircleCI can grok?

When you build your config in .circleci/config.yml you’re used to working with a few structures: jobs, commands (or steps) and workflows. You may also have worked with executor.

A job you consume (yours or one from an orb) consumes an executor - that executor might come from an orb, or be defined by you inline.

That executor defines what execution environment the commands inside the job run in - a full virtual machine, or a docker container. A well-defined job in an orb might make these configurable via parameters.

A job is filled with steps - and each of those steps are commands. All commands inside a single job run in the same instance of the defined executor. Other jobs run in different instances, even if they use the same definition.

A command you consume is also a series of steps (more commands). There are 3 types of commands: defined by you, defined in an orb, or a circleci builtin.

Reusable config

So how do we make a job, command, or executor something we can reuse in multiple projects (or make available to the public to use)?

That’s where the orb comes in.

These same (hopefully) familiar concepts are published in a library that CircleCI calls an orb.

Questions?

If you have more questions, I’m happy to dig deep into this! Schedule a free 30 minute call

tl;dr

A CircleCI orb is just a library of reusable yaml in a specific structure with a distribution mechanism. And like any library, it has it’s own build/test/publish cycle, has expectations of dependancies, and has it’s own level of “code quality” - so always review the code before you use it!