How to set up a CircleCI pipeline with workflows

What and why

CircleCI runs pipelines defined in a single config file. Jobs do the work, workflows orchestrate the order and conditions, and orbs package reusable config. This tutorial builds a test-then-deploy pipeline.

Prerequisites

• A repository connected to CircleCI.
• An app with commands to test and build.
• Basic YAML knowledge.

Steps

1. Create the config file

Add .circleci/config.yml. CircleCI reads this path to discover your pipeline.

2. Define an executor and job

version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run: npm ci
      - run: npm test

The docker executor defines the environment; steps run the commands.

3. Add a workflow

workflows:
  build-deploy:
    jobs:
      - test
      - deploy:
          requires: [test]

Workflows declare dependencies, so deploy runs only after test succeeds.

4. Use an orb

orbs:
  node: circleci/node@5

Orbs bundle reusable jobs and commands, such as Node setup with caching, so you write less config.

5. Gate deploy on a branch

      - deploy:
          requires: [test]
          filters:
            branches:
              only: main

Filters restrict deploy to the default branch, so feature branches stop after tests.

Verification

Push a commit and open the CircleCI dashboard. The workflow should show test running first and deploy only on main. A failed test should block deploy.

Next Steps

Add caching to speed up installs. Use contexts to share secrets across projects securely. Split long jobs and parallelize test execution to cut total time.