Skip to content
Learni
View all tutorials
DevOps

How to Configure CircleCI for Your Projects in 2026

12 minBEGINNER
CI/CDCircleCI
Lire en français

Introduction

CircleCI is a continuous integration and deployment platform that enables you to automate your development workflows. In 2026, it remains a reference tool for teams seeking greater reliability and speed. This tutorial walks you through creating the configuration file and running your first pipeline.

Prerequisites

  • A free CircleCI account
  • A GitHub or GitLab repository
  • Basic command line knowledge
  • Node.js installed locally for the example

Initialize the CircleCI Project

terminal
mkdir mon-projet
cd mon-projet
git init
npm init -y

We create a new project and initialize a Git repository. This allows you to later connect the repository to CircleCI for automatic change detection.

Create the Configuration Folder

terminal
mkdir -p .circleci

CircleCI always looks for its configuration file in the .circleci folder at the project root.

Basic Configuration

.circleci/config.yml
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm install
      - run: npm run build

workflows:
  version: 2
  build_and_test:
    jobs:
      - build

This YAML file defines a simple job that installs dependencies and builds the Node.js project. It uses an official Docker image maintained by CircleCI.

Add a Testing Step

.circleci/config.yml
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm install
      - run: npm run build
  test:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm install
      - run: npm test

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

We add a separate test job that only runs after the build. This demonstrates job dependencies within a workflow.

Complete Configuration with Caching

.circleci/config.yml
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm install
      - save_cache:
          paths:
            - node_modules
          key: v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm run build
  test:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
      - run: npm test

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

Adding restore_cache and save_cache significantly speeds up builds by reusing dependencies across runs.

Best Practices

  • Always version the config.yml file
  • Use official and pinned Docker images
  • Cache dependencies to reduce build time
  • Separate build, test, and deploy jobs
  • Protect sensitive environment variables

Common Mistakes to Avoid

  • Forgetting the version field at the top of the YAML file
  • Not activating the project in the CircleCI interface after pushing
  • Using commands that require root privileges without sudo
  • Ignoring caching and unnecessarily increasing build times

Going Further

Check out our complete courses on continuous integration and DevOps at Learni Group.

How to Configure CircleCI for Projects in 2026 | Learni