CircleCI Cheatsheet: config.yml, Orbs and Workflows Reference

# 1. Minimal .circleci/config.yml at repo root
mkdir -p .circleci
cat > .circleci/config.yml <<'YAML'
version: 2.1

jobs:
    test:
        docker: [{ image: cimg/python:3.12 }]
        steps:
            - checkout
            - run: pip install -r requirements.txt
            - run: pytest -q

workflows:
    ci:
        jobs: [test]
YAML

git add .circleci/config.yml && git commit -m "ci: enable circleci" && git push

# 2. CLI — local validation + local job runs
brew install circleci                      # macOS
# Or: curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | bash

circleci version
circleci setup                             # interactive token setup

# 3. Validate config without pushing
circleci config validate                   # syntax + semantic check
circleci config process .circleci/config.yml   # show the expanded YAML (after orbs)

# 4. Run a single job locally (in Docker)
circleci local execute --job test

# 5. Connect a repo
#    Web UI: app.circleci.com → Projects → Set Up Project

# Full config.yml — parameters, named executor, reusable command, two jobs, a workflow.
version: 2.1

parameters:
    deploy-env:
        type: enum
        enum: [staging, production]
        default: staging

executors:
    py:
        docker: [{ image: cimg/python:3.12 }]
        resource_class: medium
        working_directory: ~/repo

commands:
    install-deps:
        parameters:
            requirements:
                type: string
                default: requirements.txt
        steps:
            - restore_cache:
                  keys:
                      - v2-pip-{{ checksum "<< parameters.requirements >>" }}
                      - v2-pip-
            - run: pip install --user -r << parameters.requirements >>
            - save_cache:
                  key:   v2-pip-{{ checksum "<< parameters.requirements >>" }}
                  paths: [~/.cache/pip]

jobs:
    test:
        executor: py
        parallelism: 4
        steps:
            - checkout
            - install-deps
            - run:
                  name: run pytest with shard splitting
                  command: |
                      TESTS=$(circleci tests glob "tests/**/test_*.py" | \
                              circleci tests split --split-by=timings)
                      pytest --junitxml=junit/${CIRCLE_NODE_INDEX}.xml $TESTS
            - store_test_results: { path: junit }

    deploy:
        executor: py
        steps:
            - checkout
            - run: ./scripts/deploy.sh << pipeline.parameters.deploy-env >>

workflows:
    ci:
        jobs:
            - test
            - deploy:
                  requires: [test]
                  filters: { branches: { only: main } }

# Orbs are versioned packages of reusable jobs / commands / executors.
version: 2.1

orbs:
    python:  circleci/python@2.1                  # CircleCI-maintained
    aws-cli: circleci/aws-cli@4.1
    slack:   circleci/slack@4.13
    docker:  circleci/docker@2.5

jobs:
    test:
        executor: python/default                  # orb-provided executor
        steps:
            - checkout
            - python/install-packages:            # orb-provided command
                  pkg-manager: pip
                  cache-version: v2
            - run: pytest -q
            - slack/notify:
                  event: fail
                  channel: ci-alerts

    publish:
        docker: [{ image: cimg/base:current }]
        steps:
            - checkout
            - setup_remote_docker: { docker_layer_caching: true }
            - aws-cli/setup:
                  role-arn:    arn:aws:iam::123:role/gh-oidc
                  role-session-name: circleci-${CIRCLE_BUILD_NUM}
            - docker/check
            - docker/build:
                  image: my-org/app
                  tag:   ${CIRCLE_SHA1}
            - docker/push:
                  image: my-org/app
                  tag:   ${CIRCLE_SHA1}

workflows:
    ci:
        jobs:
            - test
            - publish:
                  context: aws-prod                # context = org-level secret bundle
                  requires: [test]
                  filters: { branches: { only: main } }

# Caches are immutable per key. Fall through with a prefix when the exact key misses.
# Bump the version prefix (v2- → v3-) when the cache shape changes.
jobs:
    build:
        docker: [{ image: cimg/node:20.11 }]
        steps:
            - checkout

            - restore_cache:
                  keys:
                      - v3-node-{{ arch }}-{{ checksum "package-lock.json" }}
                      - v3-node-{{ arch }}-                                    # prefix fallback

            - run: npm ci --prefer-offline

            - save_cache:
                  key:   v3-node-{{ arch }}-{{ checksum "package-lock.json" }}
                  paths: [node_modules, ~/.npm]

            - run: npm run build

            # Pass artifacts between jobs in the same pipeline (ephemeral)
            - persist_to_workspace:
                  root: .
                  paths: [dist/, package.json]

    deploy:
        docker: [{ image: cimg/node:20.11 }]
        steps:
            - attach_workspace: { at: . }                                       # pulls from build
            - run: npx --yes wrangler deploy

# Docker Layer Caching for image builds
# (requires the "Docker Layer Caching" feature on your plan):
#   - setup_remote_docker:
#         docker_layer_caching: true
#   - run: docker build -t my-app .

# CircleCI splits tests across N containers using past timing data.
# Upload junit reports → next run's split has accurate timings.
jobs:
    test:
        docker: [{ image: cimg/python:3.12 }]
        parallelism: 6                              # number of parallel containers
        steps:
            - checkout
            - run: pip install -r requirements.txt

            - run:
                  name: shard tests by historical timing
                  command: |
                      # Each container picks a different shard
                      TESTS=$(circleci tests glob "tests/**/test_*.py" \
                              | circleci tests split --split-by=timings --timings-type=classname)
                      mkdir -p test-results
                      pytest --junitxml=test-results/junit-${CIRCLE_NODE_INDEX}.xml $TESTS

            - store_test_results: { path: test-results }     # feeds future timing splits

            - run:
                  name: e2e (only on the first container)
                  command: ./scripts/e2e.sh
                  when: always
                  # Skip on non-zero CIRCLE_NODE_INDEX
                  # by using a conditional shell test:
                  # [ "$CIRCLE_NODE_INDEX" -ne 0 ] && circleci-agent step halt

# End-to-end pipeline: lint → test (parallel) → build → manual approval → deploy.
version: 2.1

orbs:
    node:  circleci/node@5.2
    slack: circleci/slack@4.13

executors:
    node-20:
        docker: [{ image: cimg/node:20.11 }]
        resource_class: medium

jobs:
    lint:
        executor: node-20
        steps:
            - checkout
            - node/install-packages: { cache-version: v3 }
            - run: npm run lint

    test:
        executor: node-20
        parallelism: 4
        steps:
            - checkout
            - node/install-packages: { cache-version: v3 }
            - run:
                  command: |
                      TESTS=$(circleci tests glob "test/**/*.spec.ts" \
                              | circleci tests split --split-by=timings)
                      npx jest --reporters=jest-junit $TESTS
            - store_test_results: { path: junit }

    build:
        executor: node-20
        steps:
            - checkout
            - node/install-packages: { cache-version: v3 }
            - run: npm run build
            - persist_to_workspace: { root: ., paths: [dist/] }

    deploy:
        executor: node-20
        steps:
            - attach_workspace: { at: . }
            - run: ./scripts/deploy.sh
            - slack/notify: { event: pass, channel: deploys }

workflows:
    ci:
        jobs:
            - lint
            - test
            - build:  { requires: [lint, test] }
            - hold:   { type: approval, requires: [build], filters: { branches: { only: main } } }
            - deploy: { context: aws-prod, requires: [hold] }