CircleCI Config: config.yml, Orbs & Workflow Guide

config.yml Structure

CircleCI configuration lives at .circleci/config.yml. Use version: 2.1 to access orbs, commands, and executors. Jobs define the work; workflows orchestrate job order and conditions.

version: 2.1

orbs:
  node: circleci/[email protected]
  slack: circleci/[email protected]

executors:
  node-executor:
    docker:
      - image: cimg/node:20.0
    resource_class: medium

jobs:
  test:
    executor: node-executor
    parallelism: 4
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Split and run tests
          command: |
            TESTFILES=$(circleci tests glob "src/**/*.test.ts" | \
              circleci tests split --split-by=timings)
            npx jest $TESTFILES --ci --runInBand
      - store_test_results:
          path: test-results/
      - slack/notify:
          event: fail
          template: basic_fail_1

  build:
    executor: node-executor
    steps:
      - checkout
      - node/install-packages
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths: [dist]

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

Caching Strategies

Proper caching is the single biggest lever for build speed in CircleCI. Cache dependencies on the lockfile checksum and always provide a fallback key to avoid cold-cache runs on every dependency change.

steps:
  - restore_cache:
      keys:
        # Exact match on lockfile — fastest cache hit
        - node-deps-v2-{{ checksum "package-lock.json" }}
        # Fallback: restore most recent cache for this branch
        - node-deps-v2-{{ .Branch }}-
        # Final fallback: any cache
        - node-deps-v2-

  - run: npm ci

  - save_cache:
      key: node-deps-v2-{{ checksum "package-lock.json" }}
      paths:
        - ~/.npm
        - node_modules/

  # Workspaces pass artifacts between jobs in the same workflow
  - persist_to_workspace:
      root: ~/project
      paths: [dist/]

# In a downstream job:
  - attach_workspace:
      at: ~/project

Machine Executor for Docker Builds

When you need to build Docker images or run Docker Compose services, switch to the machine executor. It gives you a full Ubuntu VM with Docker pre-installed and support for Docker layer caching — which can reduce image build time by up to 80%.

build-image:
  machine:
    image: ubuntu-2204:current
    docker_layer_caching: true   # requires Performance plan
  steps:
    - checkout
    - run:
        name: Build and push Docker image
        command: |
          echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin
          docker build -t myorg/myapp:$CIRCLE_SHA1 .
          docker tag myorg/myapp:$CIRCLE_SHA1 myorg/myapp:latest
          docker push myorg/myapp:$CIRCLE_SHA1
          docker push myorg/myapp:latest

CircleCI vs GitHub Actions vs Travis CI