YAML Quickstart guide - CircleCI

The crux of connecting CircleCI to your project is a config.yml, which is held in a .circleci directory. CircleCI configuration files are written in YAML, a more human-friendly data serialization format for programming languages. YAML is a strict superset of JSON, so anything you can do in JSON, you can also do in YAML. CircleCI YAML configurations will largely consist of key-value pairs, and nested key-value pairs.

The most basic configuration file will need a CircleCI version, an execution environment, and a job to run.

CircleCI version

Your .circleci/config.yml will start off with the version of CircleCI you wish to use. CircleCI cloud and newer server versions should be using CircleCI 2.1.

# CircleCI configuration file

version: 2.1

Execution environment

Next, your configuration needs a job to run, and an execution environment for that job to run in. The following are CircleCI’s supported execution environments:

  • Docker

  • Linux VM (virtual machine)

  • macOS

  • Windows

  • GPU

  • Arm

There are some limitations depending on the execution environment in your configuration. Visit the Introduction to Execution Environments page to get started in that section of our documentation, which has extensive information on each execution environment.

In the .circleci/config.yml file, we will add a Docker execution environment to our job build.

# CircleCI configuration file
version: 2.1

jobs:
  build:
    docker:
    # Primary container image where all steps run
     - image: cimg/base:2022.05

jobs is a collection of steps which are executed as a unit, either within a fresh container, or a virtual machine. In this example, jobs is being built within a Docker container, which is set up in the configuration using nested key-pairs. docker is calling a pre-built CircleCI Docker image, cimg/base, an Ubuntu Docker image. The image in this example contains the minimum tools required to operate a build on CircleCI, as well as Docker.

Images are used by either a Docker or machine executor. In our example, we are using a Docker convenience image that spins up an Ubuntu environment. If we used macOS as an execution environment, we could use a machine image instead, which would spin up a dedicated virtual machine with Xcode preinstalled, as in the example below.

# CircleCI configuration file
version: 2.1

jobs:
  build:
    macos:
      xcode: 13.3.0

You will notice that the key-value pairs do not follow the same syntax. Each execution environment will be set up a little differently. You can refer to our execution environment documentation, or visit the CircleCI developer hub to find a list of convenience images and machine images, and their syntax.

The developer hub also has a list of available CircleCI orbs, which are shareable packages of configuration you can use to simplify your builds. Visit the Slack Orb Tutorial page for instructions on how to set up one of the most popular orbs.

CircleCI jobs and workflows

The last thing we need for a basic CircleCI configuration is a job to actually run. Jobs are orchestrated using workflows, which is a set of rules defining a collection of jobs and their run order. Using the Docker configuration example, we can add steps to our job. Steps are a list of commands to run inside the Docker container.

# CircleCI configuration file
version: 2.1

jobs:
  build:
    docker:
     - image: cimg/base:2022.05
    steps:
        - run: echo "Say hello to YAML!"

This very basic example is only running one job, build, which means there is also only one workflow running in the background. If a second job is added, workflows will need to be defined explicitly, to orchestrate the run order. Job names can be updated to reflect the job when workflows is added. If there is only one job defined, the job must be named build, as in the example above.

A second job, and workflows defining run order, is shown in the example below.

# CircleCI configuration file
version: 2.1

jobs:
  # Job one with a unique name
  say_hello:
    docker:
     - image: cimg/base:2022.05
    steps:
      - run: echo "Say hello to YAML!"
  # Job two with a unique name
  say_goodbye:
    docker:
     - image: cimg/base:2022.05
    steps:
      - run: echo "Say goodbye to YAML!"

workflows:
  # Name of workflow
  hello_and_goodbye:
    # List of jobs that will run
    jobs:
      - say_hello
      - say_goodbye

If you have a CircleCI account, you can create a new project and add these examples to a .circleci/config.yaml file. You can see the strings printed out in the job’s build pipeline in the CircleCI web UI.

YAML can be quite picky about indentations. You can use a YAML checker to parse your YAML and make sure it is valid.

If you would like a more complex configuration tutorial, visit the Configuration Tutorial page. Before starting this tutorial, you should already have a CircleCI account set up, as you will follow along in the CircleCI web UI. You can also find a variety of configuration examples on the Sample Configuration page.

VS Code extension

If you use VS Code, you might find the official CircleCI extension useful when writing, editing, navigating and troubleshooting your YAML Config files.

The extension provides real-time syntax highlighting and validation, improved navigation through go-to-definition and go-to-reference commands, usage hints and autocomplete suggestions.

Screenshot showing the definition available on hover

Authenticating the extension with your CircleCI account will also allow you to visualize and manage your CircleCI pipelines directly from VS Code, and be notified of workflow status changes. The CircleCI VS Code extension is available to download on the VS Code marketplace.

Fun with YAML

Below are some fun examples of other YAML syntax that might become handy as you create more complex configuration files.

Multi-line strings

If the value is a multi-line string, use the > character, followed by any number of lines. This is especially useful for lengthy commands.

haiku: >
  Please consider me
  As one who loved poetry
  Oh, and persimmons.

Note: Quotes are not necessary when using multiline strings.

Sequences

Keys and values are not restricted to scalars. You may also map a scalar to a sequence.

scalar:
  - never
  - gonna
  - give
  - you
  - up

Items in sequences can also be key-value pairs.

simulation:
  - within: "a simulation"
  - without:
      a_glitch: "in the matrix"

Note: Remember to properly indent a key-value pair when it is the value of an item in a sequence.

Anchors and aliases

To DRY up your .circleci/config.yml, use anchors and aliases. Anchors are identified by an & character, and aliases by an * character.

song:
  - &name Al
  - You
  - can
  - call
  - me
  - *name

When the above list is read by a YAML parser, the literal output looks like this.

song:
  - Al
  - You
  - can
  - call
  - me
  - Al

Merging maps

Anchors and aliases work for scalar values, but to save maps or sequences, use << to inject the alias.

default: &default
  school: hogwarts

harry:
  <<: *default
  house: gryffindor

draco:
  <<: *default
  house: slytherin

You can also merge multiple maps.

name: &harry_name
  first_name: Harry
  last_name: Potter

address: &harry_address
  street: 4, Privet Drive
  district: Little Whinging
  county: Surrey
  country: England

harry_data:
  <<: [*harry_name, *harry_address]

Note: As mentioned in a YAML repository issue, it is possible to merge maps, but not sequences (also called arrays or lists). For a more complex example, see this gist.

Comments

Post a Comment

Popular posts from this blog

Different Types of Reports in Scrum - Agile

Image
  Introduction to Agile Reporting I’m not going to elaborate on the Agile Framework itself here.  1. Sprint Burndown At a Sprint-level, the burndown presents the  easiest way to track and report status  (the proverbial  Red / Amber / Green ), i.e., whether your Sprint is on or off-track, and what are the chances of meeting the Sprint goals. The burndown chart – when used right – can provide  near-real time updates  on Sprint progress. “If your team do it right, then they would take in just the right amount of work into a sprint.” At the beginning of a Sprint, the Scrum team perform Sprint Planning and agree to take on development work worth a certain number of Story points. This forms the basis for the Sprint Burndown chart. The total story points agreed at the beginning of the sprint make up the y-axis, and the individual dates in the Sprint make up x-axis. If your team do it right, then they would take in just the right amount of work into ...
Read more

Terraform

Image
  Terraform is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently. HashiCorp Terraform is an infrastructure as code tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to provision and manage all of your infrastructure throughout its lifecycle. Terraform can manage low-level components like compute, storage, and networking resources, as well as high-level components like DNS entries and SaaS features. How does Terraform work? Terraform creates and manages resources on cloud platforms and other services through their application programming interfaces (APIs). Providers enable Terraform to work with virtually any platform or service with an accessible API. HashiCorp and the Terraform community have already written  thousands of providers  to manage many different types of resources...
Read more

Scrum Master Interview help - Bootcamp

Understanding the MoSCoW prioritization | How to implement it into your project Projects, irrespective of their size or complexity, often juggle numerous tasks and requirements. In such a scenario,  MoSCoW prioritization  becomes essential to ensure the successful completion of the project.  Besides, it is also a very effective way to manage project priorities. With a straightforward and adaptable approach, the MoSCoW method helps manage stakeholder expectations and improve project outcomes. What is the MoSCoW prioritization technique?  The MoSCoW method is a prioritization matrix widely used in project management and software development. The term MoSCoW is an acronym that stands for  Must have ,  Should have ,  Could have , and  Won’t have , each denoting a level of priority. Here is the breakdown of the MoSCoW method:  Must have:  These are critical requirements that the project cannot be completed withou...
Read more