CircleCI Orbs & Custom Docker Images - When to use Which

Hey Everyone! I wanted to share some thoughts on the different CircleCI Ecosystem assets we have and when you might want to use which.

CircleCI Orbs and Docker Convenience Images extend the CircleCI Platform enabling high levels of customization, flexibility, and shorter build times.

How are they made?

CircleCI Orbs are packages of reusable CircleCI configuration a.k.a YAML. Orbs are translated into the final CircleCI config on the fly at the beginning of a pipeline.

Convenience Images are simply Docker images but created with Continuous Integration builds in mind. They are created ahead of time and then used as the build environment within a pipeline’s jobs.

When should you use which?

Convenience images or your own custom Docker images have a lot of benefits because they are made once and then can be run again and again for every build. Convenience images work best when the workload can be done before the build:

  • requires a lot of CPU time/processing
  • downloading of large files
  • network use which is slow
  • actions that are highly cacheable

CircleCI Orbs work best when work needs to be done at runtime and when logic needs to be shared across projects and communities:

  • Runtime logic and changes to the build environment
  • Parameterized input and CircleCI jobs
  • Reuse of CircleCI config
  • Automate actions such as:
    • Running tests or deployments
    • Issuing commands to a CLI
    • Executing scripts

Ultimately They Work Best Together

At the end of the day, CircleCI Orbs and Convenience Images work best when used together. The former for runtime work and the latter for ahead of time work. Together they allow users to make the powerful CircleCI platform work best for their specific use cases.