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.
orbs, commands, and 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
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 checkout.
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.
executors
Much like the commands key allows you to reuse steps the executors key allows you to reuse executors.
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.
jobs
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!
parameters
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.
- string
- boolean
- steps
- enum
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
Orbs are collections of jobs, executors, commands, and more. Here’s a great example from the docs:
version: 2.1
orbs:
codecov: circleci/codecov-clojure@0.0.4
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 orbs. Like jobs, commands, and 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 jobs, commands, and 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.
The first orb in the list is a registered orb. It’s similar to the inline orb except it lives in the 
instead of the config. We have a repository for orbs (like npm for javascript code) and they can be imported into a 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.
conditional steps
Two new keys called when and 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.
The condition subkey is meant to evaluate as true or 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 true. The 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: somenamespace/foo@1.2
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 pre-steps or 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 pre-steps and post-steps.
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.
