CircleCI Orbs are a way to package and share reusable configuration for your CI/CD workflows.
Let’s see an Orbs in action. Imagine you want to deploy to AWS Elastic Container Registry (ECR). Instead of writing out the aws-cli commands and authentication steps every time, you can use the circleci/aws-ecr Orb.
Here’s a snippet of a .circleci/config.yml file using it:
version: 2.1
orbs:
aws-ecr: circleci/aws-ecr@7.0.0
jobs:
build-and-push:
docker:
- image: cimg/base:2023.07
steps:
- checkout
- aws-ecr/build-and-push-image:
account-url: 123456789012.dkr.ecr.us-east-1.amazonaws.com
region: us-east-1
repo: my-app-repo
tag: ${CIRCLE_SHA1}
workflows:
build-workflow:
jobs:
- build-and-push
When this job runs, CircleCI will fetch the aws-ecr Orb, which contains pre-defined commands and executors. The aws-ecr/build-and-push-image command is a specific job defined within that Orb. It handles logging into AWS, building your Docker image, tagging it, and pushing it to the specified ECR repository. The account-url, region, repo, and tag are parameters you provide to customize the Orb’s behavior for your specific needs.
The fundamental problem Orbs solve is configuration duplication and maintenance overhead. Without them, every project needing to, say, deploy to AWS, run a specific security scan, or integrate with a third-party service would have to write and maintain that logic independently. This leads to inconsistencies, bugs, and significant wasted engineering time. Orbs allow teams to create a "source of truth" for common CI/CD patterns.
Internally, an Orb is a collection of reusable CI/CD components. These can include:
- Jobs: A complete set of steps to perform a task (e.g.,
build-and-pushjob in the ECR example). - Commands: A sequence of steps that can be invoked within a job (e.g., a
deploycommand that abstracts multiple deployment steps). - Executors: Pre-configured Docker images or resource classes that jobs can run on.
- Workflows: While less common, you can define workflow structures within an Orb.
When you reference an Orb like circleci/aws-ecr@7.0.0, CircleCI downloads that Orb’s definition. Your .circleci/config.yml then uses the components (jobs, commands, etc.) defined within that Orb. The @7.0.0 part is crucial; it pins your configuration to a specific version of the Orb, ensuring that your builds remain stable even if the Orb author releases breaking changes in future versions. You can update versions explicitly when you’re ready.
The levers you control are the parameters passed to the Orb’s components. These are defined by the Orb’s author. For the aws-ecr Orb, you control the AWS account details, the Docker image name, the region, and how the image is tagged. If an Orb doesn’t expose a parameter you need, you might have to fork the Orb or add custom steps around its usage.
Many Orbs are developed and maintained by CircleCI itself (like circleci/aws-ecr, circleci/node, circleci/python), but the Orb registry is open to the community. This means you can find Orbs for almost any common task, or even publish your own.
When you use a command from an Orb, like aws-ecr/build-and-push-image, you’re not just running a few shell commands. The Orb’s definition includes an executor (often a specific Docker image designed for the task), and a sequence of steps. For the ECR Orb, this includes steps to authenticate with AWS using credentials you’ve securely stored in CircleCI, build your Docker image using docker build, tag it with the provided information, and then push it using docker push. The Orb encapsulates all the necessary logic and dependencies, abstracting away the complexity.
The registry doesn’t just host Orbs; it also hosts their source code on GitHub. This is fantastic because if you’re curious about how an Orb actually works, or if you need to customize it, you can go directly to the source. You can see the exact jobs, commands, and parameters that make up the Orb. This transparency is a huge benefit for debugging and understanding.
The most surprising thing about Orbs is that they are essentially just YAML definitions hosted in a registry. When you use circleci/aws-ecr@7.0.0, CircleCI isn’t downloading a compiled binary or a complex plugin. It’s fetching a config.yml file from the Orb registry and merging its contents into your build’s configuration. This makes Orbs incredibly flexible and easy to inspect.
The next step after mastering Orbs is exploring how to create your own custom Orbs to standardize your team’s unique workflows.