Writing YAML
This document describes the most important features of YAML for use in CircleCI configuration.
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.
See also
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.
- For a concrete example of keys and values, see the Configuring CircleCI document.
- If you are unsure whether your
config.yml
is valid YAML, run it through a validator.
CircleCI has also developed “orbs,” which enable you to use pre-configured and tested packages of configuration elements that you can use in your configuration workflow. Utilizing DRY (Don’t Repeat Yourself), orbs enable you to quickly and easily incorporate configuration elements (jobs, executors, commands) in your workflow. For more detailed information about orbs:
- Refer to Orb Introduction, for a high-level overview of orbs.
- Refer to Orb Intro, for more about how to use existing orbs.
- Refer to Creating Orbs, where you will find step-by-step instructions on how to create your own orb.
- Refer to Reusing Config for more detailed examples of reusable orbs, commands, parameters, and executors.
- For a more exhaustive overview of YAML, Learn X in Y Minutes has a great summary.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.