CircleCI Cheat Sheet
Reference for CircleCI config.yml syntax, orbs, workflows, and executors for building continuous integration pipelines.
Basic Config
Minimal CircleCI 2.1 configuration with a single job.
version: 2.1jobs: build: docker: - image: cimg/node:20.10 steps: - checkout - run: npm ci - run: npm testworkflows: main: jobs: - build
Orbs & Workflows
Using orbs and multi-job workflows with dependencies.
version: 2.1orbs: node: circleci/[email protected]jobs: test: executor: node/default steps: - checkout - node/install-packages - run: npm test deploy: docker: - image: cimg/base:2024.01 steps: - run: ./deploy.shworkflows: build-test-deploy: jobs: - test - deploy: requires: - test filters: branches: only: main
Key Concepts
Core CircleCI configuration building blocks.
- jobs- Named units of work, each with its own executor and steps
- executors- Reusable execution environments (docker, machine, macos) referenced by jobs
- orbs- Shareable, versioned packages of config (commands, jobs, executors)
- workflows- Orchestrate job order, parallelism, and fan-in/fan-out via requires
- caching- save_cache/restore_cache steps persist dependencies between builds
- contexts- Named groups of secrets shared securely across projects
Dependency Caching
Manual cache save/restore using a checksum key.
steps: - checkout - restore_cache: keys: - v1-deps-{{ checksum "package-lock.json" }} - run: npm ci - save_cache: key: v1-deps-{{ checksum "package-lock.json" }} paths: - node_modules
Matrix Jobs with Parameters
Run a job across a matrix of parameter values to test multiple runtime versions in parallel.
version: 2.1jobs: test: parameters: node-version: type: string docker: - image: cimg/node:<< parameters.node-version >> steps: - checkout - run: npm ci - run: npm testworkflows: matrix-test: jobs: - test: matrix: parameters: node-version: ["18.19", "20.10", "21.6"]
Test Splitting Across Parallel Runners
Split a test suite across multiple containers using timing data to balance load.
jobs: test: docker: - image: cimg/node:20.10 parallelism: 4 steps: - checkout - run: npm ci - run: name: Run split tests command: | TESTFILES=$(circleci tests glob "test/**/*.spec.js" | \ circleci tests split --split-by=timings) npx jest $TESTFILES
Reusable Commands
Define a parameterized command once and invoke it from multiple jobs to avoid duplicated steps.
commands: install_and_cache: parameters: cache-key: type: string default: "v1-deps" steps: - restore_cache: keys: - << parameters.cache-key >>-{{ checksum "package-lock.json" }} - run: npm ci - save_cache: key: << parameters.cache-key >>-{{ checksum "package-lock.json" }} paths: [node_modules]jobs: build: docker: - image: cimg/node:20.10 steps: - checkout - install_and_cache: cache-key: "v2-deps" - run: npm run build
Workspaces & Artifacts Across Jobs
Persist build output from one job and attach it in a downstream job, then upload artifacts for inspection.
jobs: build: docker: [{ image: cimg/node:20.10 }] steps: - checkout - run: npm run build - persist_to_workspace: root: . paths: [dist] deploy: docker: [{ image: cimg/base:2024.01 }] steps: - attach_workspace: at: . - run: ./deploy.sh dist - store_artifacts: path: dist destination: build-output
Advanced Pipeline Features
Lesser-known CircleCI features useful in production pipelines.
- dynamic config- setup: true plus a continuation orb generates config.yml at runtime for monorepo path-filtering
- approval jobs- type: approval pauses a workflow until a human clicks Approve in the UI
- pipeline parameters- pipeline.parameters values passed via API trigger or scheduled pipelines to change behavior per run
- no_output_timeout- per-step override to allow long-running commands that produce no stdout without being killed
- self-hosted runners- machine: type: <runner-resource-class> executes jobs on infrastructure you control
- SSH debugging- Rerun a failed job 'with SSH' to shell into the exact failed container for live debugging
- contexts + security groups- Restrict which contexts (secrets) a branch or org member can invoke via approval + restrictions
Use 'workflows.<name>.jobs.<job>.requires' to fan-out independent jobs in parallel and only fan-in for deploy, cutting overall pipeline wall-clock time significantly.