Configuring CI/CD for Your Website with CircleCI
CircleCI is a cloud-based CI/CD platform focused on speed. It uses the concept of orbs (reusable configuration packages) and resource classes for fine-tuning resources per job. Configuration is stored in .circleci/config.yml.
Basic Configuration
version: 2.1
orbs:
node: circleci/[email protected]
jobs:
test:
docker:
- image: cimg/node:20.11
steps:
- checkout
- node/install-packages:
pkg-manager: npm
- run:
name: Run tests
command: npm test
build:
docker:
- image: cimg/node:20.11
steps:
- checkout
- node/install-packages:
pkg-manager: npm
- run: npm run build
- persist_to_workspace:
root: .
paths:
- dist/
deploy:
docker:
- image: cimg/base:2024.01
steps:
- attach_workspace:
at: .
- add_ssh_keys:
fingerprints:
- "SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
- run:
name: Deploy via rsync
command: |
rsync -avz --delete dist/ deploy@$DEPLOY_HOST:/var/www/mysite/
workflows:
build-test-deploy:
jobs:
- test
- build:
requires:
- test
- deploy:
requires:
- build
filters:
branches:
only: main
Workspaces
persist_to_workspace / attach_workspace is a mechanism for passing files between jobs in a single workflow. Build artifacts (the dist/ folder) are created in the build job and picked up in the deploy job. This works faster than caching because data is stored in CircleCI's in-memory storage for the duration of the workflow.
Orbs
Orbs are reusable configuration blocks published in the registry. They save dozens of lines of YAML:
orbs:
aws-s3: circleci/[email protected]
slack: circleci/[email protected]
jobs:
deploy_s3:
docker:
- image: cimg/python:3.12
steps:
- attach_workspace:
at: .
- aws-s3/sync:
from: dist/
to: s3://my-bucket/
arguments: --delete
- slack/notify:
event: pass
template: basic_success_1
Popular orbs: circleci/aws-s3, circleci/kubernetes, circleci/docker, circleci/slack, circleci/heroku.
Resource Classes
Different jobs require different resources. Tests can run on small machines, while Docker image builds need more:
jobs:
lint:
resource_class: small # 1 CPU, 2GB RAM — cheaper
docker:
- image: cimg/node:20.11
build_docker:
resource_class: large # 4 CPU, 8GB RAM
machine:
image: ubuntu-2204:current
Classes: small, medium (default), medium+, large, xlarge, 2xlarge. Cost in credits is proportional.
Parallel Test Execution
CircleCI can automatically split test suites across N parallel containers:
test:
parallelism: 4
docker:
- image: cimg/node:20.11
steps:
- checkout
- node/install-packages
- run:
name: Split and run tests
command: |
TESTFILES=$(circleci tests glob "**/*.test.ts" | circleci tests split --split-by=timings)
npx jest $TESTFILES
- store_test_results:
path: test-results/
circleci tests split --split-by=timings splits files based on historical execution time data, balancing load across containers. With 4 containers, tests run approximately 4x faster.
Conditional Steps and Approval
workflows:
deploy:
jobs:
- build
- hold:
type: approval # waits for manual click in UI
requires:
- build
- deploy_production:
requires:
- hold
filters:
branches:
only: main
type: approval is a pause job that requires confirmation in CircleCI UI. Useful for production deployments.
SSH Access to Failed Builds
When a build fails, you can reconnect to the container:
circleci ssh --job JOB_ID
Or enable in configuration:
- run:
when: on_fail
command: sleep 600 # keeps container for 10 minutes for SSH debugging
Storing Artifacts and Test Results
- store_artifacts:
path: dist/
destination: build-output
- store_test_results:
path: test-results/
Artifacts are available in the UI on the Artifacts tab. Test results in JUnit XML format are displayed on the Tests tab with breakdown by suites.
Implementation Timeline
First working pipeline — 1 day: creating .circleci/config.yml, adding SSH keys and environment variables to the project, debugging. Complete configuration with parallel tests, orbs, and approval flow — 2–3 days.