Circleci

---
name: circleci
description: "Covers CircleCI CI/CD platform: config.yml, orbs, workflows, jobs, executors, caching, Docker layer caching, contexts, and self-hosted runners. WHEN: \"CircleCI\", \"config.yml CircleCI\", \"orbs\", \"CircleCI workflow\", \"CircleCI executor\", \"Docker layer caching\", \"CircleCI context\", \"CircleCI runner\"."
license: MIT
---

# CircleCI Expert

This skill covers CircleCI, a managed CI/CD platform optimized for fast builds and Docker-native workflows. Configuration is via `.circleci/config.yml`. CircleCI is a managed service with continuous updates.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md`
   - **Architecture** -- Load `references/architecture.md`
   - **Best practices** -- Load `references/best-practices.md`

2. **Load context** -- Read the relevant reference file.

3. **Recommend** -- Provide `config.yml` examples with `circleci` CLI commands.

## Core Concepts

### Config Structure

```yaml
# .circleci/config.yml
version: 2.1

orbs:
  node: circleci/node@6.0
  aws-cli: circleci/aws-cli@4.0

executors:
  node-executor:
    docker:
      - image: cimg/node:22.0
    resource_class: medium

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

  test:
    executor: node-executor
    parallelism: 4
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Run tests
          command: |
            circleci tests glob "test/**/*.test.ts" | \
            circleci tests split --split-by=timings | \
            xargs npm test --

  deploy:
    executor: node-executor
    steps:
      - attach_workspace:
          at: .
      - aws-cli/setup
      - run:
          name: Deploy
          command: ./deploy.sh

workflows:
  build-test-deploy:
    jobs:
      - build
      - test:
          requires: [build]
      - deploy:
          requires: [test]
          filters:
            branches:
              only: main
          context: production-aws
```

### Executors

| Executor | Isolation | Use Case |
|---|---|---|
| **Docker** | Container | Most builds, fast startup |
| **Machine** | Full VM (Linux) | Docker-in-Docker, kernel access |
| **macOS** | macOS VM | iOS/macOS builds |
| **Windows** | Windows VM | .NET, Windows-specific |
| **ARM** | ARM VM | ARM architecture builds |
| **Self-hosted runner** | Your infrastructure | Private networks, custom hardware |

### Resource Classes

| Class | CPU | RAM | Cost |
|---|---|---|---|
| `small` | 1 vCPU | 2 GB | 5 credits/min |
| `medium` | 2 vCPU | 4 GB | 10 credits/min |
| `medium+` | 3 vCPU | 6 GB | 15 credits/min |
| `large` | 4 vCPU | 8 GB | 20 credits/min |
| `xlarge` | 8 vCPU | 16 GB | 40 credits/min |
| `2xlarge` | 16 vCPU | 32 GB | 80 credits/min |

### Orbs (Reusable Packages)

```yaml
orbs:
  node: circleci/node@6.0           # Node.js setup, caching
  docker: circleci/docker@2.0        # Docker build/push
  aws-cli: circleci/aws-cli@4.0      # AWS CLI setup
  kubernetes: circleci/kubernetes@1.0 # kubectl setup
  slack: circleci/slack@4.0           # Slack notifications
  terraform: circleci/terraform@3.0   # Terraform CLI

# Orbs provide commands, jobs, and executors
jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - node/install-packages    # Orb command (handles caching)
```

### Caching

```yaml
steps:
  - restore_cache:
      keys:
        - deps-v1-{{ checksum "package-lock.json" }}
        - deps-v1-    # Fallback to partial match
  - run: npm ci
  - save_cache:
      key: deps-v1-{{ checksum "package-lock.json" }}
      paths:
        - node_modules

# Docker Layer Caching (DLC) — premium feature
jobs:
  build-image:
    machine:
      image: ubuntu-2404:current
      docker_layer_caching: true    # Cache Docker build layers
    steps:
      - checkout
      - run: docker build -t myapp .
```

### Test Splitting

```yaml
jobs:
  test:
    parallelism: 4    # Run 4 containers in parallel
    steps:
      - checkout
      - run:
          name: Split and run tests
          command: |
            # Split tests across containers by historical timing data
            TESTS=$(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)
            bundle exec rspec $TESTS
      - store_test_results:
          path: test-results    # Upload for timing data (improves future splits)
```

### Workspaces

```yaml
# Persist files between jobs in a workflow
jobs:
  build:
    steps:
      - run: npm run build
      - persist_to_workspace:
          root: .
          paths: [dist, package.json]

  deploy:
    steps:
      - attach_workspace:
          at: .    # Restores dist/ and package.json
      - run: ./deploy.sh
```

### Contexts (Shared Secrets)

```yaml
# Contexts group environment variables for sharing across projects
workflows:
  deploy:
    jobs:
      - deploy:
          context:
            - aws-production     # Injects AWS credentials
            - slack-notifications
```

### Pipeline Parameters

```yaml
# Trigger with parameters via API
parameters:
  deploy_env:
    type: string
    default: staging

jobs:
  deploy:
    steps:
      - run: echo "Deploying to << pipeline.parameters.deploy_env >>"

# Trigger via API
# curl -X POST https://circleci.com/api/v2/project/gh/org/repo/pipeline \
#   --data '{"parameters": {"deploy_env": "production"}}'
```

## CLI Reference

```bash
# Validate config
circleci config validate

# Run locally
circleci local execute --job build

# Process config (expand orbs, parameters)
circleci config process .circleci/config.yml

# Test splitting
circleci tests glob "test/**/*.test.ts"
circleci tests split --split-by=timings < test-files.txt
```

## Reference Files

- `references/architecture.md` — Execution model, orb internals, caching architecture, workspace storage, parallelism and test splitting
- `references/best-practices.md` — Config organization, orb usage, caching strategy, Docker optimization, cost management, migration guides
- `references/diagnostics.md` — Config validation errors, cache misses, resource class issues, SSH debugging, orb resolution failures