Writing YAML

This document describes the most important features of YAML for use in CircleCI configuration.

How to Write YAML
See Also

Overview

YAML is a human-friendly data serialization standard for all programming languages. It is a strict superset of JSON, another data serialization language. This means it can do everything JSON can… and more.

CircleCI configuration is stored in a single YAML file located at ~/.circleci/config.yml, where ~ is the root of your project’s directory. Since most of your work with CircleCI occurs in this file, it is important to understand the basics of YAML formatting.

How to Write YAML

The basic structure of a YAML file is a hash map and consists of one or more key-value pairs.

key: value

You can set another key-value pair as a value by indenting the nested key.

key:
  another_key: "another value"

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

Search Results for ""