Using dynamic configuration
On This Page
The following examples of dynamic configuration usage are provided below:
A basic example
The following is a basic example using CircleCI’s dynamic configuration feature. In this example, we assume that a
generate-config script already exists. The script outputs a new configuration YAML based on some type of work it performs. It could potentially inspect
git history, pipeline values that get passed to it, or anything else you might do from inside a
version: 2.1 # this allows you to use CircleCI's dynamic configuration feature setup: true # the continuation orb is required in order to use dynamic configuration orbs: continuation: firstname.lastname@example.org # our defined job, and its steps jobs: setup: executor: continuation/default steps: - checkout # checkout code - run: # run a command name: Generate config command: | ./generate-config > generated_config.yml - continuation/continue: configuration_path: generated_config.yml # use newly generated config to continue # our single workflow, that triggers the setup job defined above workflows: setup: jobs: - setup
In the above configuration, we:
Add the line
setup: trueto the top-level of our config, to designate it for use of CircleCI’s dynamic configuration feature
continuationorb so we can use it.
Define a job called
setupthat uses the
continuationorb as an
executor. This job:
checkoutstep to checkout code from the configured repository.
runstep to execute the existing
generate-configscript, so we can pass its output to the
continuejob of the
Continues running the pipeline based on what configuration is provided to the required
Lastly, we call the
setupjob defined above as a part of our
| You can only use one workflow per |
steps based on which files are modified
You may find that you would like to conditionally run a
step based upon changes made to a specific fileset. This would be beneficial in the case of your code/microservices being stored in a monorepo, or a single repository.
To achieve this, CircleCI has provided the
path-filtering orb, which allows a pipeline to continue execution based upon the specific paths of updated files.
For example, consider a monorepo structure like the example shown below:
. ├── .circleci │ ├── config.yml │ └── continue_config.yml ├── service1 │ ├── Service1.java ├── service2 │ ├── Service2.java ├── tests │ ├── IntegrationTests.java
An example implementation of CircleCI’s dynamic configuration for the above use case can be found in the following
version: 2.1 # this allows you to use CircleCI's dynamic configuration feature setup: true # the path-filtering orb is required to continue a pipeline based on # the path of an updated fileset orbs: path-filtering: email@example.com workflows: # the always-run workflow is always triggered, regardless of the pipeline parameters. always-run: jobs: # the path-filtering/filter job determines which pipeline # parameters to update. - path-filtering/filter: name: check-updated-files # 3-column, whitespace-delimited mapping. One mapping per # line: # <regex path-to-test> <parameter-to-set> <value-of-pipeline-parameter> mapping: | service1/.* run-build-service-1-job true service2/.* run-build-service-2-job true base-revision: main # this is the path of the configuration we should trigger once # path filtering and pipeline parameter value updates are # complete. In this case, we are using the parent dynamic # configuration itself. config-path: .circleci/continue_config.yml
version: 2.1 orbs: maven: firstname.lastname@example.org # the default pipeline parameters, which will be updated according to # the results of the path-filtering orb parameters: run-build-service-1-job: type: boolean default: false run-build-service-2-job: type: boolean default: false # here we specify our workflows, most of which are conditionally # executed based upon pipeline parameter values. Each workflow calls a # specific job defined above, in the jobs section. workflows: # when pipeline parameter, run-build-service-1-job is true, the # build-service-1 job is triggered. service-1: when: << pipeline.parameters.run-build-service-1-job >> jobs: - maven/test: name: build-service-1 command: 'install -DskipTests' app_src_directory: 'service1' # when pipeline parameter, run-build-service-2-job is true, the # build-service-2 job is triggered. service-2: when: << pipeline.parameters.run-build-service-2-job >> jobs: - maven/test: name: build-service-2 command: 'install -DskipTests' app_src_directory: 'service2' # when pipeline parameter, run-build-service-1-job OR # run-build-service-2-job is true, run-integration-tests job is # triggered. see: # https://circleci.com/docs/configuration-reference/#logic-statements # for more information. run-integration-tests: when: or: [<< pipeline.parameters.run-build-service-1-job >>, << pipeline.parameters.run-build-service-2-job >>] jobs: - maven/test: name: run-integration-tests command: '-X verify' app_src_directory: 'tests'
In the above configuration, we:
Add the line
setup: trueto the top-level of our config, to designate it for use of CircleCI’s dynamic configuration feature.
mavenorbs so we can use them.
Define two boolean pipeline parameters,
Define four jobs:
check-updated-filesjob will use the
path-filteringorb to determine which files have changed, according to the file-path provided. It will also set the designated pipeline parameters to their specified values (in this case, different maven commands will be triggered based on which files changed).
build-service-1job uses the
mavenorb to compile/install the service1 code, but skips any tests
build-service-2job uses the
mavenorb to compile/install the service2 code, but skips any tests
run-integration-testsjob uses the
mavenorb to run any integration tests
Define four workflows, three of which are conditionally executed:
service-1workflow triggers the
build-service-1job when the pipeline parameter value mapped to run-build-service-1-job is set to
service-2workflow triggers the
build-service-2job when the pipeline parameter value mapped to run-build-service-2-job is set to
run-integration-testsworkflow will run if the
run-build-service-2-jobpipeline parameters have been updated to
truebased on the results of the
check-updated-filesworkflow will always run any time this pipeline is triggered
path-filtering orb documentation for more information on available elements and required parameters.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guidefirst).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.