CircleCI Cheatsheet

Table of Contents

1. CircleCI Basics
2. CircleCI Configuration
3. CircleCI Orbs
4. CircleCI Workflows
5. CircleCI Jobs and Steps
6. CircleCI Executors
7. CircleCI Environment Variables
8. CircleCI Caching
9. CircleCI Artifacts
10. CircleCI with Docker
11. CircleCI with Kubernetes
12. CircleCI Approval Jobs
13. CircleCI API
14. CircleCI Best Practices
15. Troubleshooting CircleCI

CircleCI Basics

What is CircleCI?

CircleCI is a continuous integration and continuous delivery platform that automates the build, test, and deployment of software.

Key Components

• .circleci/config.yml file: Defines the CI/CD pipeline
• Workflows: Orchestrate jobs
• Jobs: Collections of steps
• Steps: Individual commands or actions
• Orbs: Reusable packages of CircleCI configuration

CircleCI Configuration

Basic .circleci/config.yml structure

version: 2.1

orbs:
  node: circleci/node@5.0.2

workflows:
  sample-workflow:
    jobs:
      - build-and-test

jobs:
  build-and-test:
    docker:
      - image: cimg/node:18.1.0
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          name: Run tests
          command: npm test

CircleCI Orbs

Use an orb

orbs:
  node: circleci/node@5.0.2

Create a custom orb

1. Create an orb project
2. Define orb in orb.yml
3. Validate and publish orb:

circleci orb validate orb.yml
circleci orb publish orb.yml namespace/orb@dev:first

CircleCI Workflows

Define a workflow

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

Parallel jobs

workflows:
  version: 2
  build-test:
    jobs:
      - build
      - test-1:
          requires:
            - build
      - test-2:
          requires:
            - build

CircleCI Jobs and Steps

Define a job

jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run:
          name: Build application
          command: make build

Use conditional steps

steps:
  - run:
      name: Run tests
      command: |
        if [ "${CIRCLE_BRANCH}" == "develop" ]; then
          make test
        fi

CircleCI Executors

Docker executor

jobs:
  build:
    docker:
      - image: cimg/node:18.1.0

Machine executor

jobs:
  build:
    machine:
      image: ubuntu-2004:current

macOS executor

jobs:
  build:
    macos:
      xcode: 14.2.0

CircleCI Environment Variables

Built-in environment variables

• CIRCLE_BRANCH: The name of the Git branch currently being built
• CIRCLE_SHA1: The SHA1 hash of the last commit of the current build
• CIRCLE_BUILD_NUM: The number of the current build
• CIRCLE_PROJECT_USERNAME: The GitHub or Bitbucket username of the current project
• CIRCLE_PROJECT_REPONAME: The GitHub or Bitbucket repo name of the current project

Custom environment variables

Set in CircleCI UI: Project Settings > Environment Variables

Use environment variables

steps:
  - run:
      name: Print custom variable
      command: echo $MY_CUSTOM_VAR

CircleCI Caching

Save cache

steps:
  - save_cache:
      paths:
        - ~/project/node_modules
      key: npm-packages-{{ checksum "package-lock.json" }}

Restore cache

steps:
  - restore_cache:
      keys:
        - npm-packages-{{ checksum "package-lock.json" }}

CircleCI Artifacts

Store artifacts

steps:
  - store_artifacts:
      path: test-results
      destination: tr1

Store test results

steps:
  - store_test_results:
      path: test-results

CircleCI with Docker

Build and push Docker image

jobs:
  build-and-push:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Build and push Docker image
          command: |
            docker build -t myorg/myapp:$CIRCLE_SHA1 .
            echo $DOCKER_PWD | docker login -u $DOCKER_LOGIN --password-stdin
            docker push myorg/myapp:$CIRCLE_SHA1

CircleCI with Kubernetes

Deploy to Kubernetes

jobs:
  deploy-to-k8s:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - kubernetes/create-or-update-resource:
          resource-file: k8s/deployment.yml
          resource-name: deployment/myapp

CircleCI Approval Jobs

Add manual approval step

workflows:
  version: 2
  build-test-approve-deploy:
    jobs:
      - build
      - test:
          requires:
            - build
      - hold:
          type: approval
          requires:
            - test
      - deploy:
          requires:
            - hold

CircleCI API

Trigger a pipeline via API

curl -X POST https://circleci.com/api/v2/project/:vcs-type/:org/:repo/pipeline   -H "Circle-Token: $CIRCLE_TOKEN"   -H "Content-Type: application/json"   -d '{"branch":"main"}'

Get project pipelines

curl https://circleci.com/api/v2/project/:vcs-type/:org/:repo/pipeline   -H "Circle-Token: $CIRCLE_TOKEN"

CircleCI Best Practices

1. Use workflows to organize jobs
2. Leverage orbs for common tasks
3. Use caching to speed up builds
4. Parallelize tests when possible
5. Use appropriate executors
6. Store artifacts and test results
7. Use environment variables for configuration
8. Implement proper error handling and notifications
9. Use contexts for shared environment variables
10. Regularly update CircleCI configuration and orbs

Troubleshooting CircleCI

SSH into build

1. Enable SSH in job configuration:

jobs:
  build:
    steps:
      - run:
          name: Enable SSH
          command: |
            mkdir -p ~/.ssh
            echo 'github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==' >> ~/.ssh/known_hosts
      - add_ssh_keys:
          fingerprints:
            - "SO:ME:FIN:G:ER:PR:IN:T"

2. Use CircleCI UI to get SSH command

View build artifacts

Go to your project's build page > Artifacts tab

Common issues

• Build timeouts: Optimize build steps or increase timeout in job configuration
• Caching issues: Clear cache and rebuild
• Environment variable problems: Check variable names and values in CircleCI UI
• Docker-related issues: Check Docker version and image compatibility