circleci

name	circleci
description	Configure CircleCI workflows and orbs for continuous integration and deployment. Create config.yml pipelines, use orbs for reusable configurations, and optimize build performance. Use when working with CircleCI for CI/CD automation.
license	MIT
metadata	{"author":"devops-skills","version":"1.0"}

CircleCI

Build, test, and deploy applications using CircleCI's cloud-native CI/CD platform.

When to Use This Skill

Use this skill when:

• Setting up CI/CD pipelines with CircleCI
• Using orbs for reusable configuration
• Optimizing build times with caching and parallelism
• Configuring CircleCI workflows and approvals
• Managing CircleCI contexts and secrets

Prerequisites

• CircleCI account connected to repository
• Project enabled in CircleCI dashboard
• Basic YAML understanding

Configuration File

Create .circleci/config.yml:

version: 2.1

orbs:
  node: circleci/node@5.2
  docker: circleci/docker@2.4

executors:
  default:
    docker:
      - image: cimg/node:20.10
    working_directory: ~/project

jobs:
  build:
    executor: default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Build application
          command: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist

  test:
    executor: default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Run tests
          command: npm test

  deploy:
    executor: default
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Deploy
          command: ./deploy.sh

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test
          filters:
            branches:
              only: main

Executors

Docker Executor

executors:
  node:
    docker:
      - image: cimg/node:20.10
      - image: cimg/postgres:15.0
        environment:
          POSTGRES_USER: test
          POSTGRES_DB: testdb
    working_directory: ~/app

Machine Executor

executors:
  linux-machine:
    machine:
      image: ubuntu-2204:current
    resource_class: large

macOS Executor

executors:
  macos:
    macos:
      xcode: "15.0.0"
    resource_class: macos.m1.medium.gen1

Caching

Dependency Caching

jobs:
  build:
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-deps-{{ checksum "package-lock.json" }}
            - v1-deps-
      - run: npm ci
      - save_cache:
          key: v1-deps-{{ checksum "package-lock.json" }}
          paths:
            - node_modules

Multi-Key Caching

- restore_cache:
    keys:
      - v1-{{ .Branch }}-{{ checksum "package-lock.json" }}
      - v1-{{ .Branch }}-
      - v1-main-
      - v1-

Workspaces

Persist Data

jobs:
  build:
    steps:
      - checkout
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths:
            - dist
            - node_modules

  deploy:
    steps:
      - attach_workspace:
          at: ~/project
      - run: ./deploy.sh

Parallelism

Test Splitting

jobs:
  test:
    parallelism: 4
    steps:
      - checkout
      - run:
          name: Run tests
          command: |
            TESTFILES=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
            npm test -- $TESTFILES
      - store_test_results:
          path: test-results

Workflows

Sequential Jobs

workflows:
  pipeline:
    jobs:
      - build
      - test:
          requires:
            - build
      - deploy:
          requires:
            - test

Parallel Jobs

workflows:
  pipeline:
    jobs:
      - build
      - test-unit:
          requires:
            - build
      - test-integration:
          requires:
            - build
      - deploy:
          requires:
            - test-unit
            - test-integration

Manual Approval

workflows:
  deploy-prod:
    jobs:
      - build
      - test
      - hold:
          type: approval
          requires:
            - test
      - deploy-production:
          requires:
            - hold

Scheduled Workflows

workflows:
  nightly:
    triggers:
      - schedule:
          cron: "0 2 * * *"
          filters:
            branches:
              only:
                - main
    jobs:
      - build
      - test

Branch Filtering

workflows:
  build-deploy:
    jobs:
      - build:
          filters:
            branches:
              only:
                - main
                - /feature-.*/
      - deploy:
          filters:
            branches:
              only: main
            tags:
              only: /^v.*/

Orbs

Using Orbs

version: 2.1

orbs:
  aws-cli: circleci/aws-cli@4.1
  kubernetes: circleci/kubernetes@1.3

jobs:
  deploy:
    executor: aws-cli/default
    steps:
      - aws-cli/setup:
          aws_access_key_id: AWS_ACCESS_KEY_ID
          aws_secret_access_key: AWS_SECRET_ACCESS_KEY
      - kubernetes/install-kubectl
      - run: kubectl apply -f k8s/

Common Orbs

orbs:
  node: circleci/node@5.2              # Node.js
  docker: circleci/docker@2.4          # Docker builds
  aws-cli: circleci/aws-cli@4.1        # AWS CLI
  aws-ecr: circleci/aws-ecr@9.0        # ECR push
  aws-ecs: circleci/aws-ecs@4.0        # ECS deploy
  gcp-cli: circleci/gcp-cli@3.1        # GCP CLI
  kubernetes: circleci/kubernetes@1.3  # K8s deploy
  slack: circleci/slack@4.12           # Notifications

Docker Builds

version: 2.1

orbs:
  docker: circleci/docker@2.4

jobs:
  build-and-push:
    executor: docker/docker
    steps:
      - setup_remote_docker:
          version: 20.10.24
      - checkout
      - docker/check
      - docker/build:
          image: myorg/myapp
          tag: $CIRCLE_SHA1
      - docker/push:
          image: myorg/myapp
          tag: $CIRCLE_SHA1

Environment Variables

Project Variables

Set in CircleCI Project Settings > Environment Variables

Contexts

workflows:
  deploy:
    jobs:
      - deploy-staging:
          context: staging-secrets
      - deploy-production:
          context: production-secrets

Using Variables

jobs:
  deploy:
    steps:
      - run:
          name: Deploy
          command: |
            aws s3 sync dist/ s3://$S3_BUCKET
          environment:
            AWS_DEFAULT_REGION: us-east-1

Artifacts and Test Results

jobs:
  test:
    steps:
      - run:
          name: Run tests
          command: npm test -- --coverage
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: coverage
          destination: coverage-report

Resource Classes

jobs:
  build:
    docker:
      - image: cimg/node:20.10
    resource_class: large  # 4 vCPU, 8GB RAM
    steps:
      - checkout
      - run: npm run build

# Available classes:
# small: 1 vCPU, 2GB RAM
# medium: 2 vCPU, 4GB RAM (default)
# large: 4 vCPU, 8GB RAM
# xlarge: 8 vCPU, 16GB RAM

Common Issues

Issue: Cache Not Restoring

Problem: Cache misses on every build Solution: Verify cache key format, ensure checksum file hasn't changed

Issue: Workspace Attach Fails

Problem: Cannot find persisted workspace Solution: Ensure persist_to_workspace job completed, check paths

Issue: Docker Layer Caching

Problem: Docker builds are slow Solution: Enable Docker Layer Caching in project settings (paid feature)

Best Practices

• Use orbs for common tasks
• Implement aggressive caching strategies
• Use workspaces for sharing data between jobs
• Split tests with parallelism for faster builds
• Use contexts for environment-specific secrets
• Define reusable executors
• Store test results for insights

Related Skills

• github-actions - GitHub CI/CD
• docker-management - Container builds
• aws-ecs-fargate - ECS deployments