Documentation structure for LLMs (llms.txt)
CircleCI Logo

Config templating

21 minutes ago
Cloud Server v4+

CircleCI can update your .circleci/config.yml at compile time using pipeline values and parameters. This config templating lets you insert values and check conditions.

Insert a pipeline value

Wrap a pipeline value or pipeline parameter in << and >> to insert it into a string or field:

Insert a pipeline value into a job step
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - run: echo "This pipeline is on << pipeline.git.branch >>"
Insert a pipeline parameter into a job image
version: 2.1

parameters:
  image-tag:
    type: string
    default: "current"

jobs:
  build:
    docker:
      - image: cimg/base:<< pipeline.parameters.image-tag >>
    steps:
      - checkout

For the full list of values you can insert, see the Pipeline Values and Parameters page.

The YAML merge key <<: is a different feature. See Merging Maps in the YAML introduction.

Add logic with expressions

Expressions add comparison and logic operators to this templating syntax. Use them to set a field from a condition, or to decide whether a job or workflow runs.

The job filters, and workflow when and unless fields accept expressions directly. For other fields wrap the expression in << and >>.

Direct expression in a job filter
version: 2.1

parameters:
  run-storybook-tests:
    type: boolean
    default: false

...
# jobs configuration omitted for brevity

workflows:
  build:
    jobs:
      - setup
      - storybook-tests:
# The "storybook-tests" job only runs if the "setup" job completes successfully AND if either the "run-storybook-test"s pipeline parameter is true OR the branch name is "dry-run-deploy" OR the branch name starts with "deploy".
          requires:
            - setup
          filters: |
            pipeline.parameters.run-storybook-tests
            or pipeline.git.branch == "dry-run-deploy"
            or pipeline.git.branch starts-with "deploy"
Direct expression in a workflow when clause
workflows:
  nightly-run-workflow:
# The "nightly-run-workflow" workflow only runs if the branch name is "main" OR "staging".
    when: pipeline.git.branch == "main" or pipeline.git.branch == "staging"
    jobs:
      - build
      - deploy:
          requires:
            - build
Direct expression in a workflow unless clause
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - checkout

workflows:
  feature-workflow:
    unless: pipeline.git.branch == "main"
    jobs:
      - build
Expression wrapped in << and >>
version: 2.1

jobs:
  test:
    docker:
      - image: cimg/base:current
    parallelism: << pipeline.git.branch == "main" and 10 or 1 >>
    steps:
      - checkout

For operators and more examples, see Using Expressions in Your Configuration.

How this differs from dynamic configuration

Config templating edits the config you already have, before CircleCI assembles the pipeline. Dynamic Configuration uses a setup workflow to generate or continue with a different config at runtime.

Next steps