CircleCI 2.1 Config Overview

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 :cloud: 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.

10 Likes

trying to make this work - documentation is leaving me frustrated. getting error seconds into the build. have workflow version 2.1 and enabled Enable build processing


Config Processing Error00:00
Exit code: 1
#!/bin/sh -eo pipefail
# Unsupported or missing workflows config version
false
Exited with code 1
1 Like

It sounds like you may not have enabled build processing in your project settings. Can you DM me a link to the job with the failure? I can take a look.

Looking at that error, it looks like you might have put version: 2.1 under workflows rather than at the top level. In config version 2.1, you no longer need any version under workflows–only at the top level.

Right way:

version: 2.1
workflows:
  # workflows go here, no version needed

Wrong:

version: 2
workflows:
  version: 2.1

Hello,

How can one tell Circle 2.1 is working? I didn’t see that mentioned anywhere in the docs. I changed my config to 2.1, but my builds still say “2.0”.

Thanks for Circle,
Aaron

If you can use any of the features listed above without your jobs spontaneously combusting then you’re using 2.1. You can also check to see if “Build Processing” is enabled at the bottom of your projects “Advanced Settings”. If that’s enabled then the 2.1 features will be available.

1 Like

Thanks to add features, and I already used it. Good improvements.

What I need mention are:

  1. For exist project in Circle CI, if you get weird behaviour after you change from version: 2 to version: 2.1 , please check if you have active Enable build processing (preview)

It wasted several hours to me to finger this solution out.

  1. The document to mix executors and parameters in one example confused me a lot at beginning. Until I realised they are separated features.

  2. A suggestion. This forum closed tickets too quick. I asked a question before. With new features in version 2.1, I can fix it. But now I can’t update or reply my own question any more.

With above question, I have solution with version 2.1 . But it is bad that I can’t update it. It doesn’t make sense for me to close discussion in any open forum.

Within Github/issues, I agree with this auto-close feature. But this is a open forum, why close tickets so quickly. All discussion should be keep updating.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.