CircleCI 2.1 Config Overview
Version 2.1 of the CircleCI
config.yml is available to try out for your projects. You can enable it by turning on
Build Processing in the Advanced Settings of your projects settings page. Here’s a brief overview of some of the changes you’ll have access to in 2.1.
executors are new faces in the
config.yml party. Also, workflows no longer have a version number. Make sure to take the version key out of your workflows section or bad things will happen. The only version key in 2.1 is the top-level key.
version: 2.1 orbs: commands: executors: jobs: workflows:
commands are basically a collection of
steps. Like any steps that you would define as part of a job in your
jobs section. in fact - they are used right in the steps much like existing commands such as
version: 2.1 commands: my-command: steps: - run: echo "a command is a collection of steps" - run: echo "this command has two steps" jobs: my-job: steps: - my-command
In the simplified config above a command named
my-command has two steps defined. When
my-command is called in the
steps of a job section it will expand to include all of the
steps defined within it. You can also use commands within other
commands. If you have a common set of steps you can define them in a single command for reuse in multiple locations.
Check out the docs here for more details on using the new commands key.
Much like the
commands key allows you to reuse
executors key allows you to reuse
version: 2.1 executors: my-executor: docker: - image: python my-other-executor: docker: - image: ruby jobs: my-job: executor: my-executor steps: - run: echo "i'm using my-executor" my-job2: executor: my-other-executor steps: - run: echo "i'm using my-other-executor"
Jobs have a key called
executor. Passing it the name of the executor will use all of the configured values for that job.
Checkout out the docs here for more details on using the new executors key.
While the jobs section of the config isn’t new there is one key difference in 2.1. You can now use jobs multiple times in your workflows section. Also, in 2.1 they support parameters. What’s that? glad you asked!
All three of the above keys support a sub-key called
parameters. This adds extra customizability to each of the keys.
commands: copy-markdown: parameters: destination: description: destination directory type: string default: docs steps: - cp *.md << parameters.destination >>
There are four different parameter types and the docs dig into them really well. Definitely worthwhile reading the section for each type as they can each be used for different purposes.
For instance, with a string parameter, you can expand that string in other places using a special syntax. The syntax looks like
<< parameters.param-name >>. The command defined above can now have a custom folder name passed into it. If one is not passed into the command it will use the defined default.
jobs: my-job: executor: some-executor steps: - copy-markdown: destination: docs2
Check out the docs for more details on using the new parameters key.
Orbs are collections of
commands, and more. Here’s a great example from the docs:
version: 2.1 orbs: codecov: firstname.lastname@example.org my-orb: executors: default: docker: - image: circleci/ruby:1.4.2 commands: dospecialthings: steps: - run: echo "We will now do special things" jobs: myjob: executor: default steps: - dospecialthings - codecov/upload: path: ~/tmp/results.xml workflows: main: jobs: - my-orb/myjob
In this example, you can see two kinds of
executors you can define
orbs within the
config.yml itself. The second orb in the list called
my-orb is an inline orb. It contains a job called
my-job which can be used directly from the orb. To use
executors defined in an orb you prefix their reference with the orb name and a forward slash.
You can see in the
jobs section we’re accessing
myjob defined in
my-orb and calling it in the
main workflow. You can use
commands defined in an orb within the
steps section of
jobs or other
commands. You can also use
executors defined in an orb in the
executor section of a job.
config.yml for use. You can develop and register your own public orbs to use and share with our fancy new open source CLI tool.
Two new keys called
unless have been added to define steps that run when a condition is met.
unless will operate as the inverse of
when. The two new conditional steps are used in the
steps section of your config, and they require two subkeys.
condition subkey is meant to evaluate as
false and can be derived from
parameters such as the
boolean parameter. Empty string
parameters will evaluate as
false, and non-empty strings will evaluate as
steps subkey is where you can provide a list of
steps to run when the conditon is met.
jobs: myjob: parameters: preinstall-foo: type: boolean default: false machine: true steps: - run: echo "preinstall is << parameters.preinstall-foo >>" - when: condition: << parameters.preinstall-foo >> steps: - run: echo "preinstall" - unless: condition: << parameters.preinstall-foo >> steps: - run: echo "don't preinstall"
Check out the docs for more details on conditional steps.
pre-steps and post-steps
Jobs defined in a workflow can now be provided steps to run before or after the steps defined in the job itself. The syntax is simple and lives in the
workflows section of the config. Example from the docs:
version: 2.1 orbs: foo: email@example.com workflows: build: jobs: - foo/bar: pre-steps: - run: command: echo "install custom dependency" post-steps: - run: command: echo "upload artifact to s3"
bar is a job defined in the foo orb. We’re calling it within our workflow called build. By adding the
post-steps (or both) keys to the job we can add more
steps like you would in any steps section.
Check out the docs for more details on
There’s plenty more to learn so check out our reusing config docs to get all of the details for these 2.1 config changes.