Implementing Dynamic Configuration

1. Understanding Dynamic Config

Aspect	Description	Details
Dynamic Config	Definition	Configuration that is generated at runtime rather than being static, allowing for conditional logic and environment-specific settings.
Use Case	When to Use	When you need to customize workflows based on environment, branch, or other runtime conditions.
File Format	Supported Format	YAML or JSON, processed by CircleCI's configuration parser.

Example: Basic Dynamic Config

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: "Run Tests"
          command: |
            if [ "$CIRCLE_BRANCH" = "main" ]; then
              echo "Running main branch tests"
            else
              echo "Running feature branch tests"
            fi

Note: Dynamic configuration is evaluated at runtime, enabling flexibility in how jobs and workflows behave based on environment variables or branch names.

2. Enabling Dynamic Config (setup: true)

Property	Value	Description
setup	`true`	Enables dynamic configuration processing in CircleCI

Example: Enabling Dynamic Config in config.yml

version: 2.1
setup: true
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run: npm install

3. Creating Setup Workflows

Example: Basic setup workflow configuration

version: 2.1
setup: true
jobs:
  setup-job:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: npm install

Property	Description	Values
setup	Indicates if the job is a setup job	`true`
jobs	List of jobs to run in the setup workflow	Array of job definitions

Note: Setup workflows run before other workflows and can be used to prepare the environment for subsequent jobs.

4. Generating Config Dynamically

Example: Using Environment Variables in Config

version: "2.1"
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: "Run with Environment Variable"
          command: "echo $ENVIRONMENT"

Property	Description	Values
env_var	Environment variable to inject into config	`ENVIRONMENT`
value	Value to set for the environment variable	`production`

Note: Environment variables can be used to dynamically configure jobs and steps at runtime.

Example: Conditional Job Execution

version: "2.1"
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - run:
          name: "Conditional Step"
          command: "if [ $CI_COMMIT_BRANCH = 'main' ]; then echo 'Running on main'; fi"

Dynamic Configuration Best Practices

Use environment variables to inject configuration values at runtime
Implement conditional logic in steps based on branch or tag names
Avoid hardcoding sensitive values like API keys in config files

5. Using Continuation Orb

Property	Description	Values
orb	Name of the continuation orb to use	`circleci/continuation@1.0.0`
version	Version of the orb to use	`1.0.0`

Example: Using Continuation Orb

version: 2.1
orbs:
  continuation: circleci/continuation@1.0.0
jobs:
  build:
    docker:
      - image: circleci/node:16
    steps:
      - checkout
      - continuation/run:
          command: npm test

Note: The continuation orb allows you to run steps in a new job context, which is useful for long-running or resource-intensive tasks.

6. Using Path Filtering

Filter	Description	Example
only	Only run jobs when files in specified paths are modified	`only: - main - develop`
except	Exclude jobs when files in specified paths are modified	`except: - docs/* - "*.md"`

Example: Path Filtering Configuration

jobs:
  build:
    steps:
      - checkout
      - run: echo "Building..."
  test:
    steps:
      - checkout
      - run: echo "Testing..."

workflows:
  version: 2
  main:
    jobs:
      - build
      - test:
          only:
            - src/*
            - lib/*

Note: Path filtering is evaluated relative to the root of your repository.

7. Detecting Changed Files

Property	Description	Example
circleci.dynamic_config	Enables dynamic configuration processing in CircleCI	`true`
circleci.changed_files	Array of file paths that have changed since the last build	`["src/main.js", "package.json"]`

Example: Using changed files in a job

jobs:
  build:
    steps:
      - run:
          name: "Check for changed files"
          command: |
            if [[ " ${circleci.changed_files[*]} " =~ " src/main.js " ]]; then
              echo "main.js has changed"
            fi

Note: The circleci.changed_files variable is only available when using dynamic configuration and requires the circleci.dynamic_config setting to be enabled.

8. Conditionally Executing Jobs

Property	Description	Values	Notes
when	Defines when a job should run	`passed`, `failed`, `any`, `skipped`	Default is `passed`
unless	Defines when a job should NOT run	`passed`, `failed`, `any`, `skipped`	Overrides `when` if both are specified

Example: Using `when` to run a job only on failure

jobs:
  notify_on_failure:
    when: failed
    steps:
      - run: echo "Build failed, sending notification"

Example: Using `unless` to skip a job in certain conditions

jobs:
  deploy_if_needed:
    unless: skipped
    steps:
      - run: echo "Deploying to production"

9. Implementing Monorepo Support

Example: Configuring CircleCI for a Monorepo

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:18
    steps:
      - checkout
      - run:
          name: Install Dependencies
          command: npm install
      - run:
          name: Run Tests
          command: npm test
  deploy:
    docker:
      - image: circleci/node:18
    steps:
      - checkout
      - run:
          name: Deploy Service A
          command: npm run deploy:a
workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build

Property	Description	Values
version	CircleCI configuration version	`2.1`
jobs	Defines jobs to run in the workflow	Object with job definitions
workflows	Defines the workflow structure and job dependencies	Object with workflow definitions

Note: Monorepo support in CircleCI requires careful configuration of job dependencies and paths to ensure correct execution.

10. Debugging Dynamic Config

Example: Using `circleci debug` command

circleci debug --config /path/to/config.yml

Command	Description	Notes
circleci debug	Debugs configuration files	Validates config and shows parsed output

Note: The circleci debug command requires the CircleCI CLI to be installed and configured.

Example: Logging Variables in Dynamic Config

version: 2.1
jobs:
  build:
    steps:
      - run:
          name: Print Environment Variables
          command: |
            echo "CircleCI Project: $CIRCLE_PROJECT_REPONAME"
            echo "Branch: $CIRCLE_BRANCH"

Common Debugging Techniques

Use circleci debug to validate configuration syntax
Print environment variables to inspect runtime context
Utilize echo or print statements in scripts to trace execution flow
Validate dynamic values using conditional logic before applying them