A CircleCI orb is a versioned library of reusable pipeline configuration. A repository pipeline should decide when work runs and in what order; an orb can hold shared details of how jobs and commands perform that work. Jobs contain steps, and a step may invoke a command defined locally or in an orb. Both jobs and commands can take parameters. section 6.3.7
This separation matters when many repositories use the same infrastructure framework, cloud vendor, scanning tools, or secrets service. Copying those steps into every pipeline spreads maintenance work and makes cross-functional requirements harder to manage consistently. Shared orbs let a platform team improve common behavior without turning each repository’s pipeline into a large implementation. Keep genuinely unique logic in local scripts, jobs, or commands. section 6.3.7
Build the shared behavior incrementally:
- Start with a repeated tool action or command, then consider a shared job when the sequence of actions is also common. section 6.3.7
- Expose required and optional parameters for differences such as working directory, Terraform variable file, plan output, or whether to run a Checkov scan. section 6.3.7
- Provide optional step hooks where teams need to run repository-specific work after checkout, initialization, planning, or completion. section 6.3.7
Infrastructure pipeline
An IAM pipeline can declare pinned Terraform, 1Password, and pipeline-events orbs while keeping its branch filters and workflows in the repository. The Terraform orb can manage Terraform Cloud workspace settings; local workflow configuration still determines when account changes, integration tests, credential rotation, and release tasks run. This divides reusable execution behavior from repository-specific orchestration. section 6.4.4 section 6.3.7
---
version: 2.1
orbs:
terraform: twdps/terraform@3.1.1 #1
op: twdps/onepassword@3.0.0
do: twdps/pipeline-events@5.1.0
globals: #2
- &context <my-team>
- &executor-image twdps/circleci-infra-aws:alpine-2025.04
on-push-main: &on-push-main #3
branches:
only: /main/
tags:
ignore: /.*/
commands:
workflows:
The configuration shows three versioned orb imports alongside local filters, commands, and workflows—the boundary between shared pipeline code and repository-owned orchestration. section 6.4.4
Prefer an orb when behavior repeats across pipelines, but do not move every detail into one. A small set of maintained libraries can serve many teams, provide a place to manage pipeline-wide requirements, and reduce the cost of changing pipeline tools later. section 6.3.7
