CircleCI
CircleCI is a hosted CI/CD platform built around fast pipelines and reusable configuration. You describe your pipeline in .circleci/config.yml, and CircleCI runs it on Docker, Linux VM, macOS, Windows, Arm, or GPU executors. Two features set it apart: strong performance tooling (dependency caching, parallel test splitting, right-sized resource classes) and orbs, versioned packages of configuration you can share across hundreds of repositories.
It suits teams that want managed CI with fine control over compute, work across GitHub, GitLab, and Bitbucket, or need to standardize pipelines across many projects. If you're entirely on GitHub and happy with defaults, GitHub Actions is the usual alternative.
TL;DR
- Pipelines live in
.circleci/config.yml(config version2.1). - Workflows orchestrate jobs; each job runs steps in an executor with a resource class.
- Orbs package reusable jobs, commands, and executors — pin them to a version.
- Cache dependencies on a lockfile checksum; use workspaces to pass build output between jobs.
- Split tests across parallel containers by timing data to cut long suites down.
- Keep secrets in contexts restricted to specific branches or security groups.
Quick Example
A pipeline that installs once, runs tests in parallel across four containers, and deploys only from main after an approval:
store_test_results uploads JUnit timing data, which the next run's circleci tests split --split-by=timings uses to balance containers.
Core Concepts
The Building Blocks
Executors
- Docker — fastest to start; use CircleCI's convenience images (
cimg/*) or your own. Add service containers (Postgres, Redis) as extra images in the same job. - machine — a full Linux VM; needed for Docker-in-Docker-heavy work or privileged operations.
- macos — required for iOS and macOS builds with Xcode.
- windows, arm, and GPU — for platform-specific builds and ML workloads.
Caches vs Workspaces vs Artifacts
Orbs
Orbs bundle jobs, commands, and executors behind parameters. Certified orbs (published by CircleCI) and partner orbs cover Node, Python, AWS, Kubernetes, Slack notifications, and more. Organizations can publish private orbs to standardize pipelines internally.
Contexts and Security
Contexts hold environment variables (API keys, cloud credentials) at the organization level. You attach them to specific jobs and can restrict them by security group or by expression (for example, only the main branch). CircleCI also supports OIDC tokens, letting jobs assume short-lived cloud roles instead of storing long-lived keys.
Dynamic Configuration
With setup: true, a small setup workflow can generate or select the real config — for example, running only the pipelines for packages that changed in a monorepo using the path-filtering orb.
Best Practices
Key Caches on Lockfiles
The fallback key restores a close-enough cache when the lockfile changes. Bump v1 to invalidate everything.
Split Slow Test Suites
Set parallelism and split by timing data. Suites that take 20 minutes on one container often finish in five across four. Always upload test results so timing data stays accurate.
Right-Size Resource Classes
Bigger isn't always faster. Measure: CPU-bound builds (compilation, bundling) benefit from larger classes; network-bound jobs don't. Credits are billed per minute per class.
Pin Orb and Image Versions
Use exact versions (circleci/node@5.2.0, cimg/node:20.11) so pipelines don't change underneath you. Update deliberately with a dependency bot.
Use OIDC Instead of Static Cloud Keys
Configure your cloud provider to trust CircleCI's OIDC tokens and grant narrowly scoped roles. There's nothing to leak or rotate. See Secrets Management.
Keep Jobs Self-Contained
Every job should declare what it needs: checkout, attach workspace, restore cache. Implicit state is what makes pipelines flaky and hard to rerun.
Common Mistakes
Cache Keys That Never Change
Caching Build Output Instead of Using Workspaces
Caches persist across pipelines and are keyed by you; using them for per-commit build output leaks results between branches. Use persist_to_workspace for within-workflow handoff.
Secrets in Project Variables Available to Every Branch
Project-level environment variables are exposed to all jobs, including those from forks if enabled. Put production credentials in a restricted context.
Parallelism Without Splitting
Setting parallelism: 4 without circleci tests split just runs the full suite four times.
Unpinned latest Images
A base image update can break builds overnight with no config change. Pin tags.
FAQ
What are CircleCI orbs?
Orbs are reusable, versioned packages of CircleCI configuration — jobs, commands, and executors with parameters. You import them in config.yml to avoid copy-pasting common setups like installing Node or deploying to AWS.
What's the difference between a job and a workflow?
A job is one unit of work: a series of steps running in one executor. A workflow orchestrates several jobs, defining their order with requires, running independent ones in parallel, and adding branch filters or manual approvals.
How do I make CircleCI builds faster?
Cache dependencies by lockfile checksum, pass build output through workspaces instead of rebuilding, split tests across parallel containers using timing data, and choose resource classes that match the workload.
CircleCI or GitHub Actions?
GitHub Actions is the natural default for repositories on GitHub and has a huge marketplace. CircleCI stands out for test splitting, resource-class control, SSH debugging into failed jobs, and multi-SCM support. Many teams choose based on where their code lives and how much pipeline performance tuning they need.
Can I debug a failed CircleCI job?
Yes. "Rerun job with SSH" gives you a shell in the same executor with the same environment, which is often the fastest way to diagnose environment-specific failures.
Related Topics
- CI/CD — Pipeline fundamentals and practices
- GitHub Actions — The most common alternative
- GitLab CI — Integrated CI in GitLab
- Docker — Building the images executors run
- Secrets Management — Contexts, OIDC, and credential hygiene