CircleCI Dynamic Config

A CircleCI dynamic config skips unnecessary jobs.

If your PR only changes a JavaScript file, why should CI run PHPUnit tests?

If your PR only changes README.md, why should CI run any tests?

And if your PR only changes one directory in a monorepo, why should all the other directories run tests?

With a dynamic config, your builds should pass sooner.

Especially for PRs with a smaller diff.

You’ll see how to do this by only adding 30 lines of .yml to existing .yml.

And you can copy and paste most of it.

We’ll do this with an example repo.

Files In The Repo

• PHP
• JavaScript
• Miscellaneous files, like package.json and composer.json

Tests That CircleCI Runs

• PHPUnit: should only run when a .php file is changed in the PR.
• Jest: should only run when a .js file is changed.
• End to end: should run whenever a .php, .js, .json, or .yml file is changed.

First File For Dynamic Config

We’ll start with the .circleci/config.yml file:

On line 3, the setup value of true makes this file produce a dynamic config.

The path-filtering orb on line 11 looks at the PR’s diff versus the main branch.

Then, it checks which files in the mapping value are in the diff:

For example, if a .php file is in the diff, the regex on line 14 will match: .*\.php$

Then, it’ll send the parameter pipeline.parameters.run-php to the second config, with the value of true.

That’s because the 3rd value here is true:

That will tell the second config file to run the PHPUnit tests.

Second File For Dynamic Config

Next, add .circleci/continue_config.yml

This accepts parameters like pipeline.parameters.run-php, and runs the actual jobs.

Add parameters for all of the parameters in the mapping value:

These come from the 2nd values in the mapping value.

For example, the mapping:

<meta charset="utf-8">.*\.php$ run-php true Code language: HTML, XML (xml)

…has a parameter of run-php.

Then, add a workflows value:

There were 3 parameters, so there should be 3 workflows.

Name the workflows whatever you’d like, the names don’t matter.

The when conditionals determine if the workflows should run.

They have the parameters that you added to the top of the file.

And they should always begin with << pipeline.parameters.

So if the PR has a changed PHP file, pipeline.parameters.run-php will be true.

And the php-flow workflow will run.

Next, fill in the jobs section:

There’s not much to keep in mind in these jobs, as long as each job is referenced in a workflow.

Project Settings

There’s one more step to get your CircleCI dynamic config to work.

Go to your account at app.circleci.com.

Select the project > Project Settings > Advanced.

And toggle this on:

Dynamic Config In Action

This repo has PHP and JavaScript.

But there’s also an end to end test job.

That will run when either PHP or JavaScript files changed.

So its mapping regex looks for several files:

<meta charset="utf-8">.*\.(php|js|json|yml)$Code language: HTML, XML (xml)

With your CircleCI dynamic config…

When a PHP file is edited, PHP and e2e jobs run.

Not Jest (JavaScript) tests:

And when you only edit the README.md, only 1 job runs, no tests.

It succeeds in 7 seconds:

And if you’re not using CircleCI yet…

Get started with their free plan that’s like a pro plan.

• Category: CircleCI