Config Basics: Jobs, Steps & Executors

Minimal Config

# .circleci/config.yml
version: 2.1

jobs:
  build-and-test:
    docker:
      - image: cimg/node:20.11
    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]
      - run: npm test

workflows:
  main:
    jobs:
      - build-and-test

Executors

docker (a specified image, fastest to start) is the most common; machine gives a full VM, useful when Docker-in-Docker or deeper OS access is needed. Executor choice determines what tools/OS are available to the job's steps.

Caching

restore_cache/save_cache persist dependencies (node_modules, a virtualenv) between runs, keyed by a lockfile checksum — a new cache is only created when dependencies actually change.

Triggers & Branch Filters

workflows:
  main:
    jobs:
      - build-and-test
      - deploy:
          requires: [build-and-test]
          filters:
            branches:
              only: main   # only deploy from main, not feature branches