Basics > Writing YAML
This document describes the most important features of YAML for use in CircleCI configuration.
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
~ 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.
You can set another key-value pair as a value by indenting the nested key.
key: another_key: "another value"
If the value is a multi-line string,
followed by any number of lines.
This is especially useful for lengthy commands.
haiku: > Consider me As one who loved poetry And persimmons.
Note: Quotes are not necessary when using multiline strings.
Keys and values are not restricted to scalars. You can 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
use anchors and aliases.
Anchors are identified by an
and aliases by an
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
Anchors and aliases work for scalar values,
but to save maps or sequences,
<< to inject the alias.
default: &default school: hogwarts harry: <<: *default house: gryffindor draco: <<: *default house: slytherin
You can also merge multiple maps.
good: &one - harry - ron bad: &two - crabbe - goyle students: <<: [*one, *two]
For a more complex example, see this gist.
While YAML has several other features, the examples above should be enough to get you started with YAML and keep your CircleCI configuration concise. If you are hungry for more knowledge, here are a few ideas.