CircleCI

CircleCI#

CircleCI is the SaaS CI that pioneered Docker-first builds. YAML pipelines, container-image-as-environment, orbs for reusable config, generous parallelism. The operator picks it for fast, opinionated CI without running a server.

Architecture#

  • Pipeline, triggered by a VCS event or API call.

  • Workflow, an ordered + parallel set of jobs inside a pipeline.

  • Job, a unit that runs in one executor.

  • Executor, the environment a job runs in. docker (default), machine (Linux / Windows VM), macos, arm.

  • Orb, a reusable bundle of config (jobs, commands, executors) published to the registry.

Pipeline shape#

# .circleci/config.yml
version: 2.1

orbs:
  node: circleci/node@5.2.0

jobs:
  test:
    docker:
      - image: cimg/node:22.4
    resource_class: medium
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: pnpm
          override-ci-command: pnpm install --frozen-lockfile
      - run: pnpm test

  build-push:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker:
          docker_layer_caching: true
      - run: |
          echo "$GHCR_PASSWORD" | docker login ghcr.io -u "$GHCR_USER" --password-stdin
          docker build -t ghcr.io/myorg/app:$CIRCLE_SHA1 .
          docker push ghcr.io/myorg/app:$CIRCLE_SHA1

workflows:
  ci:
    jobs:
      - test
      - build-push:
          requires: [test]
          filters:
            branches:
              only: main

Executors#

Executor

Use

docker

Container-based. Fast, the default. cimg/* images cover most languages.

machine

Full Linux VM. Required for Docker-outside-of-Docker, kernel features, GPU.

macos

macOS VMs for iOS / macOS builds.

windows

Windows Server VMs.

arm

ARM64 Linux VMs.

Self-hosted runners

Operator-owned hosts running a CircleCI agent for on-prem or sensitive workloads.

Caching and workspaces#

  • Cache persists files across runs by key (e.g. dependency caches keyed on lockfile hash).

  • Workspace carries artifacts between jobs in the same workflow.

  • Artifact publishes a build output for download / API access after the workflow completes.

Triggers#

  • VCS event (push, PR), schedule (triggers block), API trigger, pipeline parameter, scheduled pipelines.

Secrets and contexts#

  • Project environment variables scoped to one project.

  • Contexts scoped to an organization, shared across projects. Restrictable to specific security groups.

  • OIDC token mintable into AWS / GCP / Azure short-lived credentials.

When to pick CircleCI#

  • SaaS CI without running a server, fast first-builds on Docker.

  • Parallel test splitting (CircleCI’s auto-split feature is mature).

  • Need for many concurrent build runners at peak times.

When to pick something else#

  • Code on GitHub, GitHub Actions removes the cross-product integration.

  • On-prem only; self-hosted runners exist but the control plane is SaaS.

  • Cost at scale; CircleCI’s credit pricing escalates with concurrency.

References#

Contents