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:
yamlversion: 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
yamlexecutors: node: docker: - image: cimg/node:20.10 - image: cimg/postgres:15.0 environment: POSTGRES_USER: test POSTGRES_DB: testdb working_directory: ~/app
Machine Executor
yamlexecutors: linux-machine: machine: image: ubuntu-2204:current resource_class: large
macOS Executor
yamlexecutors: macos: macos: xcode: "15.0.0" resource_class: macos.m1.medium.gen1
Caching
Dependency Caching
yamljobs: 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
yaml- restore_cache: keys: - v1-{{ .Branch }}-{{ checksum "package-lock.json" }} - v1-{{ .Branch }}- - v1-main- - v1-
Workspaces
Persist Data
yamljobs: 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
yamljobs: 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
yamlworkflows: pipeline: jobs: - build - test: requires: - build - deploy: requires: - test
Parallel Jobs
yamlworkflows: pipeline: jobs: - build - test-unit: requires: - build - test-integration: requires: - build - deploy: requires: - test-unit - test-integration
Manual Approval
yamlworkflows: deploy-prod: jobs: - build - test - hold: type: approval requires: - test - deploy-production: requires: - hold
Scheduled Workflows
yamlworkflows: nightly: triggers: - schedule: cron: "0 2 * * *" filters: branches: only: - main jobs: - build - test
Branch Filtering
yamlworkflows: build-deploy: jobs: - build: filters: branches: only: - main - /feature-.*/ - deploy: filters: branches: only: main tags: only: /^v.*/
Orbs
Using Orbs
yamlversion: 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
yamlorbs: 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
yamlversion: 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
yamlworkflows: deploy: jobs: - deploy-staging: context: staging-secrets - deploy-production: context: production-secrets
Using Variables
yamljobs: deploy: steps: - run: name: Deploy command: | aws s3 sync dist/ s3://$S3_BUCKET environment: AWS_DEFAULT_REGION: us-east-1
Artifacts and Test Results
yamljobs: 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
yamljobs: 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


