Skip to main content
Mapagam

Understanding CircleCI Fundamentals

1. Understanding CI/CD Concepts

Concept Description Key Benefits
Continuous Integration (CI) Automatically builds and tests code changes as they are committed to a shared repository Early detection of integration issues, improved code quality, faster feedback loops
Continuous Delivery (CD) Automatically deploys code changes to a staging or production environment after successful testing Reduced deployment time, consistent release process, faster time-to-market
Continuous Deployment Automatically deploys every code change that passes tests to production without manual intervention Zero-downtime deployments, rapid iteration, high deployment frequency

Example: CI/CD Pipeline Flow

1. Developer pushes code to main branch
2. CI server triggers build job
3. Unit tests run automatically
4. Code coverage checks pass
5. If tests pass, CD pipeline deploys to staging
6. Manual approval for production deployment

Core CI/CD Principles

  • Automated testing ensures code quality
  • Fast feedback cycles improve developer productivity
  • Consistent deployment processes reduce human error
  • Version control integration enables traceability

2. Understanding CircleCI Architecture

Component Description Key Features
Orbs Reusable configuration templates that encapsulate common CI/CD patterns and workflows. Shareable, versioned, and customizable. Can be published to the CircleCI Orb Registry.
Workflows Define the sequence and dependencies of jobs in a CI/CD pipeline. Supports parallel execution, conditional execution, and dependencies between jobs.
Jobs Units of execution that run on a runner and perform specific tasks like building, testing, or deploying code. Configurable with resource class, environment variables, and steps.
Executors Define the environment in which jobs run, such as Docker or machine executors. Supports containerized environments and virtual machines for complex setups.
Steps Individual actions or commands that make up a job, such as checking out code or running tests. Supports custom scripts, commands, and pre-built actions from orbs.

Example: Basic Workflow Configuration

version: 2.1
orbs:
  node: circleci/node@5.0.0
workflows:
  version: 2
  build-and-test:
    jobs:
      - node/test

Architecture Overview

  • CircleCI uses a distributed architecture to scale CI/CD pipelines.
  • Orbs simplify configuration by providing reusable components.
  • Workflows orchestrate jobs with flexible execution patterns.
  • Executors define runtime environments for jobs (e.g., Docker or machine).

3. Understanding Credit-Based Pricing

Plan Credits/Month Features Notes
Free 1,000 Up to 2,000 minutes/month of compute time
100% of features		 Good for individuals or small teams testing CircleCI
Pro 5,000 Up to 10,000 minutes/month of compute time
All features including parallelism and custom workflows		 Recommended for growing teams or projects with higher compute needs
Enterprise Unlimited Unlimited minutes
Advanced security features
Custom support		 For large organizations with strict compliance or high-volume needs

Example: Credit Usage Calculation

# A job that runs for 10 minutes uses 10 credits
# If a project has 5 jobs running in parallel, each job takes 10 minutes
# Total credits used = 5 * 10 = 50 credits

# Example command to check remaining credits
circleci billing credits
Note: Credits are consumed based on the compute time used by jobs in your workflows. Each minute of job execution consumes one credit.
Warning: If you exceed your monthly credit limit, builds will be queued or stopped until the next billing cycle.

4. Comparing CircleCI Plans

Plan Features Usage Limits Cost
Free
  • 2,000 credits/month
  • 1 worker
  • 10 concurrent jobs
  • Basic pipeline features
 2,000 credits/month $0
Pro
  • Unlimited credits
  • Up to 20 workers
  • Unlimited concurrent jobs
  • Advanced pipeline features
  • Custom workflows
 Unlimited $250/month
Enterprise
  • Unlimited credits
  • Up to 50 workers
  • Unlimited concurrent jobs
  • Advanced pipeline features
  • Custom workflows
  • SLA support
  • On-premise deployment
 Unlimited Custom

Free vs Pro Plan Comparison

  • Free: Ideal for individuals or small teams with limited usage needs. Limited to 2,000 credits/month and 1 worker.
  • Pro: Suitable for growing teams or organizations with higher usage demands. Offers unlimited credits, up to 20 workers, and advanced features.
  • Enterprise: Designed for large organizations requiring custom workflows, SLA support, and on-premise deployment options.

5. Understanding Execution Environments

Environment Type Description Key Features Usage Notes
Linux Standard execution environment with full Linux support
  • Ubuntu 20.04 base image
  • Supports most standard tools and languages
 Default environment; good for most use cases
macOS macOS execution environment for Apple-specific builds
  • macOS Big Sur or later
  • Xcode and Swift support
 Use for iOS/macOS app builds
Windows Windows execution environment for Windows-specific builds
  • Windows Server 2019 or later
  • Supports PowerShell, .NET, and more
 Use for Windows desktop or server app builds
Docker Containerized execution environment using Docker images
  • Custom Docker image support
  • Full control over environment
 Use for complex or custom environments

Example: Using Docker Environment

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16-browsers
    steps:
      - checkout
      - run: npm install
Note: Docker environments allow you to use any base image, giving flexibility for complex or specific build requirements.

6. Understanding Pipeline Lifecycle

Phase Description Key Actions Duration
Setup Initial phase where environment is prepared and dependencies are installed. Checkout code, restore cache, install dependencies Variable
Build Compilation and build steps are executed. Run build scripts, compile code Variable
Test Execution of tests to validate code functionality. Run unit, integration, and end-to-end tests Variable
Deploy Deployment of the application to staging or production environments. Push to deployment targets, run deployment scripts Variable

Example: Pipeline Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package.json" }}
      - run: npm install
      - save_cache:
          paths:
            - node_modules
          key: v1-dependencies-{{ checksum "package.json" }}
      - run: npm test
      - deploy:
          command: |
            if [ "${CIRCLE_BRANCH}" = "main" ]; then
              echo "Deploying to production"
            fi

Key Pipeline Concepts

  • Jobs are the basic unit of execution in a CircleCI pipeline.
  • Steps define actions within a job, such as running commands or checking out code.
  • Workflows orchestrate jobs to run them in parallel or sequentially.
  • Caching speeds up builds by reusing previously installed dependencies.
Note: The pipeline lifecycle is managed by CircleCI's orchestration engine, which ensures that each phase completes before moving to the next.

7. Understanding Config Structure

Property Description Values Notes
version Config file version 2.1 Required for CircleCI 2.1 and above
jobs Defines jobs to run Object Each job is a set of steps
workflows Defines how jobs are orchestrated Object Controls job execution order and triggers
executors Defines reusable executor configurations Object Can be referenced in jobs

Example: Basic config structure

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install
workflows:
  version: 2
  main:
    jobs:
      - build
Note: The version: 2.1 is required to use orbs and other advanced features.

Key Concepts

  • version: Must be set to 2.1 for advanced features
  • jobs: Define the actual work to be done
  • workflows: Orchestrate jobs to run in parallel or sequence
  • executors: Reusable configurations for jobs

8. Navigating CircleCI Dashboard

Section Description Access
Projects Lists all projects configured in CircleCI Dashboard → Projects
Pipelines Shows all pipeline runs for a project Project → Pipelines
Workflows Displays workflows within a pipeline Pipeline → Workflows
Jobs Shows individual jobs in a workflow Workflow → Jobs
Settings Manage project settings, environment variables, and integrations Project → Settings

Example: Dashboard Navigation Path

Dashboard
├── Projects
│   └── <Project Name>
│       ├── Pipelines
│       │   └── <Pipeline ID>
│       │       ├── Workflows
│       │       │   └── <Workflow Name>
│       │       │       └── Jobs
│       └── Settings
Note: The dashboard provides a hierarchical view of your CI/CD process, allowing you to drill down from projects to jobs.

9. Understanding Built-in Environment Variables

Variable Description Example Value
CIRCLE_BUILD_NUM Unique identifier for the build 1234
CIRCLE_SHA1 Git commit SHA1 hash abc123def456...
CIRCLE_BRANCH Git branch name main
CIRCLE_TAG Git tag name (if built from a tag) v1.0.0
CIRCLE_PROJECT_REPONAME Repository name my-app
CIRCLE_USERNAME Username of the user who triggered the build johndoe
CIRCLE_REPOSITORY_URL Repository URL https://github.com/user/repo.git
CIRCLE_WORKFLOW_ID Unique identifier for the workflow abcd1234-ef56-7890-gh12-ij34kl56mn78
CIRCLE_JOB Name of the current job build
CIRCLE_NODE_INDEX Index of the node in a parallel job 0

Example: Using Environment Variables in Config

jobs:
  build:
    steps:
      - run: echo "Build number is $CIRCLE_BUILD_NUM"
      - run: echo "Branch is $CIRCLE_BRANCH"
      - run: echo "Commit SHA is $CIRCLE_SHA1"

10. Understanding Version Requirements

Version Type Description Examples Notes
circleci/cli CircleCI CLI version circleci version Used for local testing and configuration
executor Specifies the environment for running jobs executor: machine Can be machine, docker, or resource_class
image Base image for Docker executor image: cimg/node:18.17.0 Must be a valid Docker image reference
version CircleCI orb version orbs:
  aws-cli: circleci/aws-cli@1.0.0		 Used to pin specific orb versions for stability
dockerfile Path to Dockerfile for custom builds dockerfile: .circleci/Dockerfile Used in conjunction with machine executor

Example: Setting CircleCI CLI Version

circleci version 0.1.2345

Example: Using Docker Image with Specific Version

version: 2.1
jobs:
  build:
    docker:
      - image: cimg/node:18.17.0
Note: Always pin versions in production workflows to ensure consistency and avoid unexpected behavior from updates.

Was this article helpful?

Related Cheat Sheets