---
title: "Dynamic configuration overview"
description: "A guide to using CircleCI's dynamic configuration features"
doc_version: "unversioned"
last_updated: "2026-05-01"
---

> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Dynamic configuration overview

Dynamic configuration in CircleCI is the process of describing a pipeline in which the work done is dynamically determined. Dynamic configuration is flexible. The features described in this guide allow you to create a configuration to match the requirements of your specific project.

Dynamic configuration can mean:

*   The work is determined by values passed in at runtime as _pipeline parameters_.
    
*   The configuration file is dynamically generated by the pipeline using a template rather than being static YAML.
    
*   A project’s configuration is pieced together dynamically depending on specific [Pipeline Values](https://circleci.com/docs/guides/orchestrate/pipeline-variables/) or file paths.
    
*   Using conditional logic and parameterization to determine the work to be done.
    
*   Triggering pipelines defined by configurations that exist outside the default parent `.circleci/` directory.
    

## Quickstart

### Enable dynamic configuration

Projects created **after** December 1st 2023 have dynamic config enabled by default. If this applies to your project, you can skip this step.

To enable dynamic configuration in CircleCI:

1.  In the CircleCI web app, select **Projects** in the sidebar.
    
2.  Select the ellipsis menu next to your project and select **Project Settings**.
    
3.  From the sidebar, select **Advanced**.
    
4.  Scroll to the **Enable dynamic config using setup workflows** setting, and toggle it to the "on" position, as shown below:
    
    > **Image:** Enable dynamic config in the UI
    
    Figure 1. Screenshot showing how to enable dynamic config in the UI
    

These steps make dynamic configuration features available for your project, but any _static_ `config.yml` you have previously set up will continue to work as normal.

### Use dynamic configuration

Add the key `setup: true` to the top level of your _parent_ configuration file to designate that `config.yml` as a setup configuration.

```yaml
version: 2.1

setup: true
```

For some basic examples of using dynamic configuration, see the [Using Dynamic Configuration](https://circleci.com/docs/guides/orchestrate/using-dynamic-configuration/) how-to guide.

## Config continuation constraints

Some constraints on continuing pipelines from a `setup: true` configuration are as follows:

*   The setup configuration must be `version: 2.1`.
    
*   The setup configuration must only allow one workflow to run in each pipeline. For example:
    
    *   Have only one workflow configured.
        
    *   Use logic conditions to ensure only one workflow is run for each pipeline.
        
    
*   A pipeline can only be continued once. A pipeline cannot be continued with another setup configuration. Workflow reruns will fail as part of this restriction. Rather than rerun a setup workflow you can trigger a new pipeline.
    
*   A pipeline can only be continued within six hours of its creation.
    
*   If you declare a pipeline parameter with the same name and type in both the setup and continuation configuration files, but with different default values, the default values apply respectively to each configuration.
    
*   You can set the value of a pipeline parameter declared in the continuation configuration to a value other than the default. To do so, specify the parameter’s name and value when calling the `continue` job or command from the [continuation orb](https://circleci.com/developer/orbs/orb/circleci/continuation) using the `parameters` parameter.
    
*   The `continue` job/command will fail with the error {"message":"Conflicting pipeline parameters."} when all three of these conditions occur:
    
    1.  The same pipeline parameter is declared in both the setup and the continuation configurations.
        
    2.  The `continue` job/command attempts to pass this pipeline parameter via the `parameters` parameter.
        
    3.  The pipeline is triggered via the API or via the **Trigger Pipeline** button, with a parameter value that differs from the default value specified in the setup configuration.
        
    

## How dynamic config works

CircleCI’s dynamic configuration is made up of the following resources, which can be used together to fit a variety of use cases:

*   The [`setup` config field](https://circleci.com/docs/reference/configuration-reference/#setup) allows you to designate a configuration file as _dynamic_, allowing the use of dynamic configuration features. When a configuration is dynamic (`setup: true`) the `CIRCLE_CONTINUATION_KEY` environment variable is available, which is a secret, unique-per-pipeline key that is automatically injected into the build environment for jobs that run in a _setup_ configuration.
    
    The `CIRCLE_CONTINUATION_KEY` environment variable is required to authorize the continuation of one configuration to another via the [continue a pipeline](https://circleci.com/docs/api/v2/index.html#operation/continuePipeline) API v2 endpoint. The API also accepts a configuration string, as well as a set of pipeline parameters.
    
    A _setup_ configuration:
    
    *   Continues your pipeline on to the desired next configuration.
        
    *   Can contain jobs that compute pipeline parameters, which can then be passed into an additional configuration that potentially exists in other directories.
        
    *   Can be used to generate new configurations via pre-existing scripts.
        
    
*   Use the API v2 [continue a pipeline](https://circleci.com/docs/api/v2/index.html#operation/continuePipeline) endpoint to continue a pipeline from one configuration to another. This endpoint can be used directly or via one of the dynamic configuration orbs described next.
    
*   Use the [path filtering orb](https://circleci.com/developer/orbs/orb/circleci/path-filtering) to map file paths, pipelines parameters, and configuration files to determine the work that is done when a change happens in a specific location in a repository.
    
*   Use the [continuation orb](https://circleci.com/developer/orbs/orb/circleci/continuation) to continue one configuration to another and set up any required pipeline parameters.
    

## Dynamic configuration examples

Some examples of using dynamic configuration in CircleCI include:

*   Incorporate logic to check for file changes or parameter values so that only necessary work is done in each pipeline.
    
*   Share common configuration across projects by generating project-specific sections dynamically based on parameters.
    
*   _Continue_ a pipeline, or generate and run a configuration based on where code has changed.
    
*   Split up a configuration file into reusable fragments that can be dynamically assembled.
    
*   Generate full CircleCI configurations from small company-specific configurations. For example, if you have multiple repositories with similar CI/CD requirements, you can generate a full CircleCI YAML configuration dynamically from small template configuration written in any configuration language.
    
*   When working with a language or framework that has its own configuration language, you can generate CircleCI config dynamically from existing configuration files.
    

### Use path filtering for monorepos

In a [monorepo](https://circleci.com/blog/monorepo-dev-practices/) setup:

*   Set up path filtering to set pipeline parameters and continuation configuration sources based on the location of changes in your repository.
    
*   You can use path filtering to avoid all your microservices/sub-projects being put through the entirety of your build, test, and deployment processes when any single update occurs.
    

For example, you may have multiple projects within your repository (`project_1`, `project_2`, `project_3`).  
You can use path filtering to only run tests and deployment for `project_1` if a change is made in the `project_1` file set. The [path filtering orb](https://circleci.com/developer/orbs/orb/circleci/path-filtering) is available to help simplify your configuration further.

For a full example of path filtering, see the [Dynamic Configuration How-To Guide](https://circleci.com/docs/guides/orchestrate/using-dynamic-configuration/#execute-specific-workflows-or-steps-based-on-which-files-are-modified).

### Use config splitting for microservices

For projects that consist of multiple modules, you may require a separate job/workflow to run for each module when changes are introduced.

You can split your configuration up and store the config for each module separately within the module’s directory, keeping related code and config together.

Module jobs/workflows can be stored in multiple files as _fragments_ of a configuration. Instead of using one full `.circleci/config.yml` file, you can use dynamic configuration to combine these individual fragments into a full configuration when a pipeline is triggered.

This scenario is also referred to as _config splitting_.

For an example of config splitting, see the [Dynamic Configuration](https://circleci.com/docs/guides/orchestrate/using-dynamic-configuration/#pack-generate-validate) how-to guide.

## Using dynamic configuration on CircleCI Server

For more information on managing orbs in a server installation see the [Managing Orbs](https://circleci.com/docs/server-admin/latest/operator/managing-orbs/) page.

If you are using CircleCI Server, there are a few extra steps you will need to take to use the dynamic configuration orbs.

*   You will need to import the path filtering and continuation orbs into your server installation using the following commands:
    
    These examples show importing the most recent versions of the orbs. You can also specify a SemVer version constraint to import a specific version, for example, `circleci/continuation@1.0.0`.
    
    ```yaml
    circleci admin import-orb circleci/path-filtering --host <your-server-installation-domain> --token <your-api-token>
    ```
    
    ```yaml
    circleci admin import-orb circleci/continuation --host <your-server-installation-domain> --token <your-api-token>
    ```
    

When using the path filtering orb on server, you will need to add your CircleCI Server domain to the `path-filtering/filter` job in your workflow, for example:

```yaml
workflows:
  setup-workflow:
    jobs:
      - path-filtering/filter:
          mapping: |
            packages/api/.* api true
            packages/auth/.* auth true
            packages/e2e/.* e2e true
            packages/unit/.* unit true
          # # Optional, defaults to main:
          base-revision: main
          circleci_domain: support-server-4.eks-dev.sphereci.com
```

## FAQs

### I thought pipeline parameters could only be used with the API?

Previously, this was true, but you can now set pipeline parameters dynamically, before the pipeline is executed. The pipeline parameters for the continuation configuration can be set by using the [continuation orb](https://circleci.com/developer/orbs/orb/circleci/continuation) in the setup configuration. The pipeline associated with the setup configuration can be triggered via either the API or an event in your VCS.

### Can I use a custom executor?

Custom executors can be used, but require certain dependencies to be installed for the continuation step to work (currently: `curl`, `jq`).

### What is the continuation orb?

The continuation orb assists you in managing the pipeline continuation process. The continuation orb wraps an API call to the [Continue a pipeline API endpoint](https://circleci.com/docs/api/v2/#operation/continuePipeline). Refer to the [continuation orb](https://circleci.com/developer/orbs/orb/circleci/continuation) documentation for more information.

### Is it possible to not use the continuation orb?

If you have special requirements not covered by the continuation orb, you can implement the same functionality in other ways. Refer to the [orb source code](https://circleci.com/developer/orbs/orb/circleci/continuation#orb-source) to learn how the continuation functionality is implemented with the orb.

## Next steps

*   A how-to guide for [Using Dynamic Configuration](https://circleci.com/docs/guides/orchestrate/using-dynamic-configuration/)
    
*   The [continuation orb](https://circleci.com/developer/orbs/orb/circleci/continuation)
    
*   The [Continue a pipeline API endpoint](https://circleci.com/docs/api/v2/#operation/continuePipeline)