What is YAML?
YAML, which stands for “YAML Ain’t Markup Language,” is a human-readable data serialization language. It is commonly used to create configuration files and works well with any programming language. YAML is designed for ease of use and interaction, making it a popular choice among developers.
YAML is a strict superset of JSON, another data serialization language. This means that YAML can do everything JSON can and more. Unlike JSON, YAML uses indentation and newlines to signify structure, rather than relying on brackets and braces. This makes YAML files cleaner and easier to read.
At CircleCI, we use YAML for specifying configuration, which illustrates its practical applications in real-world projects.
How to write YAML
The basic structure of a YAML file is a map. You might call this a dictionary, hash or object, depending on your programming language or mood.
Very generally, it’s keys and values all the way down:
key: value
YAML example: Scalar types
In YAML, you can use various scalar types as values, including numbers, booleans, and strings (quoted or unquoted). The first line of a CircleCI config.yml file, for example, is usually:
version: 2.1
This key-value pair sets the configuration file version to 2.1.
Words in keys can be separated by underscores, dashes, or spaces. At CircleCI, we use underscores.
Multi-line strings
If the value of a key is a multi-line string, you can use the literal block style using the pipe (|) character or the folded block style using the greater than (>) character.
The literal style is the most straightforward. It preserves newlines and indentation exactly as they are. This is particularly helpful when defining shell commands:
command: |
if [ "${CIRCLE_BRANCH}" == "master" ];
then ansible-playbook site.yml -i production;
fi
The folded style converts newlines to spaces, making the string more compact and readable when the structure of the text isn’t important. This can be useful for long text fields, such as descriptions, that should appear as a single line in the output:
description: >
This is a multiline string.
Each line in the YAML file
will be folded into a single
line in the resulting string.
Note that the leading indentation for multi-line strings will be stripped, ensuring clean and readable code.
YAML example: Collection types
All you have to do to create collections in your YAML files is use indentation:
environment:
TEST_REPORTS: /tmp/test-reports
If you have a list of things (like images), then you can denote that sequence using dashes:
docker:
- image: ubuntu:20.04
- image: mongo:4.4
command: [mongod, --smallfiles]
- image: postgres:13
Note that the second item in the sequence has two keys: image and command. The command key uses a JSON-style sequence because (remember!) YAML is a superset of JSON.
You can also create nested maps (dictionaries within dictionaries) to represent more complex configurations:
jobs:
build:
docker:
- image: circleci/python:3.8
environment:
NODE_ENV: development
steps:
- checkout
- run:
name: Install Dependencies
command: pip install -r requirements.txt
In this example, the environment key contains a nested key-value pair for an environment variable, and the steps key contains nested maps defining each step of the job. This structure helps organize complex configurations in a clear and readable manner.
A note about indentation and formatting
One crucial thing to remember is that YAML does not allow tab characters. Use spaces for indentation. Misformatted YAML files can lead to syntax errors, which might cause builds to hang. To prevent this, run your config.yml through an online YAML validator or use the CircleCI CLI.
Additional YAML tips
When working with YAML, it’s helpful to follow some best practices to ensure your configurations are error-free and easy to read. Here are some tips and common pitfalls to avoid:
Tips for Writing YAML
- Consistent indentation: Always use spaces, not tabs, for indentation. This ensures consistency and avoids syntax errors.
- Proper syntax: Ensure colons (:) and dashes (-) are followed by a space to maintain readability and correctness.
- Quotes: Use quotes for strings containing special characters or reserved words to avoid misinterpretation.
- *Comments: Add comments using the # character to explain configurations, making your YAML files easier to understand for others (and yourself).
Common pitfalls to avoid
- Indentation errors: Incorrect indentation can lead to syntax errors. Be consistent with the number of spaces you use.
- Tab characters: Tabs are not allowed in YAML files. Always convert tabs to spaces in your text editor to prevent errors.
- Trailing spaces: Remove any trailing spaces, as they can cause issues in parsing the YAML file.
- Missing colons: Ensure that each key-value pair is properly separated by a colon followed by a space to avoid misconfigurations.
By following these guidelines, you can create clean and efficient YAML configurations that are easy to maintain and debug.
Further Reading
The content in this guide should be all you need to comfortably write a config file for your CircleCI CI/CD pipeline. YAML does support additional features, which you can read about on the official site or the less intimidating (but less exhaustive) Learn X in Y minutes.
Read more:
