Setting Up Configuration Files

1. Creating Config File

Example: Basic CircleCI Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install Dependencies
          command: npm install
      - run:
          name: Run Tests
          command: npm test
workflows:
  version: 2
  build-and-test:
    jobs:
      - build

Property	Description	Values
version	Configuration file version	`2.1`
jobs	Defines the jobs to run in the workflow	Object or array of job definitions
workflows	Defines the workflows that run jobs	Object or array of workflow definitions

Note: The version: 2.1 is required for using orbs and advanced features.

2. Specifying Config Version

Version	Description	Notes
version	`2.1`	Latest stable version as of 2026
version	`3.0`	NEW Introduced in CircleCI 3.0, includes enhanced features and performance improvements

Example: Config Version Declaration

version: 2.1

Note: The version key is required and must be the first key in your configuration file.

3. Understanding Config Hierarchy

File	Scope	Description
.circleci/config.yml	Project-level	Main configuration file for the project. Defines jobs, workflows, and orbs.
config.yml	Project-level	Alternative name for the main configuration file. Only one should be used.
.circleci/continous_integration.yml	Project-level	Deprecated in favor of `.circleci/config.yml`.
.circleci/orbs.yml	Orb-level	Defines custom orbs for reuse across projects.
.circleci/workflows.yml	Project-level	Defines reusable workflows that can be shared across jobs.

Note: The .circleci/config.yml file is the primary configuration file for CircleCI. It is processed in order, and each level of configuration can override or extend the previous one.

4. Using YAML Anchors and Aliases

YAML anchors and aliases are useful for reusing configuration blocks in CircleCI workflows to avoid repetition and improve maintainability.

Feature	Description	Usage
Anchor	Defines a reusable block with an alias	`&anchor_name`
Alias	References a previously defined anchor	`*anchor_name`

Example: Reusing a Job Configuration

version: 2.1

orbs:
  node: circleci/node@5.0.0

executors:
  <<: *node_executor

jobs:
  build_and_test:
    <<: *build_job
    steps:
      - run:
          name: Run Tests
          command: npm test

  deploy:
    <<: *build_job
    steps:
      - run:
          name: Deploy
          command: npm run deploy

workflows:
  version: 2
  build_and_deploy:
    jobs:
      - build_and_test
      - deploy

Note: YAML anchors and aliases are supported in CircleCI configuration files using the <<: merge key syntax.

5. Commenting Configuration

Element	Description	Usage
# Comment	Single-line comment in configuration	Used to document configuration steps or disable parts of the config

Example: Commenting in CircleCI Config

# This is a single-line comment
version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      # This step is skipped for now
      # - run: echo "Skipping this step"
      - run:
          name: Run tests
          command: npm test

6. Validating Config Locally

Example: Using circleci-cli to validate config

circleci config validate

Option	Values	Description
circleci config validate	`circleci config validate`	Validates the configuration file against the CircleCI schema
--config	`--config <path>`	Specify a custom config file path (default: `.circleci/config.yml`)
--local	`--local`	Validate using local configuration (requires CircleCI CLI installed)

Note: The circleci config validate command checks for syntax errors and ensures that all required fields are present in your configuration file.

Warning: If validation fails, the command will exit with a non-zero status code, which can be used in CI/CD pipelines to stop execution.

7. Using Config Processing

Example: Basic config processing with environment variables

version: "2.1"
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: "Run with environment variable"
          command: |
            echo "Environment is $ENV_TYPE"
            npm run build
      - run:
          name: "Run with config processing"
          command: |
            echo "Processing config for $CIRCLE_JOB"
            echo "Branch is $CIRCLE_BRANCH"

Property	Description	Values	Notes
CIRCLE_JOB	Current job name	`build`	Available in all steps
CIRCLE_BRANCH	Branch name	`main`	Used for conditional logic
CIRCLE_SHA1	Git commit SHA	`abc123def456...`	Unique identifier for commit
CIRCLE_TAG	Tag name (if any)	`v1.0.0`	Used for release builds

Note: Environment variables are processed at runtime and can be used in commands or scripts.

Example: Conditional processing based on branch

version: "2.1"
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: "Build on main branch"
          command: |
            if [ "$CIRCLE_BRANCH" = "main" ]; then
              echo "Running main build"
              npm run build:prod
            else
              echo "Running dev build"
              npm run build:dev
            fi

Config Processing Best Practices

Use environment variables for dynamic configuration
Validate branch names before running conditional steps
Log environment variables for debugging purposes
Use CIRCLE_SHA1 to uniquely identify builds

8. Enabling Dynamic Configuration

Note: Dynamic configuration allows you to generate your CircleCI configuration at runtime using a script, which can be useful for complex setups or when configuration depends on external factors.

Property	Description	Values	Notes
setup	Enables dynamic configuration	`true`	Must be set to `true` to enable dynamic config
command	Script to generate the config	`bash -c 'echo "version: 2.1\njobs:\n build:\n docker:\n - image: circleci/node:16\n steps:\n - checkout\n - run: npm install"'`	Can be any executable command or script

Example: Enabling Dynamic Configuration

version: 2.1
setup: true
command: bash -c 'echo "version: 2.1\njobs:\n  build:\n    docker:\n      - image: circleci/node:16\n    steps:\n      - checkout\n      - run: npm install"'

9. Organizing Multi-File Configs

Example: Splitting Configuration into Multiple Files

# .circleci/config.yml
version: 2.1
orbs:
  node: circleci/node@5.0.0
jobs:
  build:
    executor: node/default
    steps:
      - checkout
      - run: npm install
      - run: npm test
  deploy:
    executor: node/default
    steps:
      - checkout
      - run: npm install
      - run: npm run deploy
workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build
      - deploy

File	Description	Usage
.circleci/config.yml	Main configuration file	Defines workflows, jobs, and orbs
.circleci/orbs.yml	Orb definitions	Reusable configuration components
.circleci/jobs.yml	Job definitions	Reusable job templates
.circleci/workflows.yml	Workflow definitions	Job execution sequences

Note: Multi-file configs are supported in CircleCI 2.1+ and require the version: 2.1 declaration.

Best Practices for Multi-File Configs

Use orbs for reusable components across projects
Split jobs into separate files when they are complex or reused
Keep workflows in a dedicated file for better readability
Use parameterized orbs to customize behavior per project

10. Setting Pipeline Parameters

Parameter	Type	Description	Default
pipeline.parameters.<name>	string	Defines a parameter for the pipeline	None
pipeline.parameters.<name>.type	string	Specifies the type of parameter (string, boolean, enum)	string
pipeline.parameters.<name>.default	any	Default value for the parameter	None
pipeline.parameters.<name>.enum	array	Valid values for enum type parameters	None

Example: Defining Pipeline Parameters

parameters:
  environment:
    type: string
    default: production
    enum: [staging, production]
  debug:
    type: boolean
    default: false

Example: Using Pipeline Parameters in Jobs

jobs:
  build:
    parameters:
      environment:
        type: string
    steps:
      - run:
          name: Set Environment
          command: echo "Running in environment: << pipeline.parameters.environment >>"