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