Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 44 ยท CI/CD Fundamentals

YAML for Pipeline Authors

Learn the YAML you need for GitHub Actions and GitLab CI: mappings, lists, strings, multi-line scripts, anchors, and the quoting traps that break pipelines.

Most pipeline files you will ever write are YAML. GitHub Actions and GitLab CI/CD use it directly, and even Jenkins users meet it in configuration, Docker Compose and Kubernetes files. YAML looks friendly, and that is exactly why it catches people out: a missing space, a stray tab or an unquoted 3.10 can turn a working pipeline red, often with an error message that points to the wrong line.

In this lesson you will learn the small part of YAML that pipelines use, the multi-line string forms that make shell scripts readable, how anchors reduce repetition, and the five traps behind most "my YAML is valid but wrong" mistakes. Then you will run a miniature YAML parser to see how indentation turns into data.

The three building blocks

YAML has only three structures. Everything else is a variation.

A mapping is a set of key: value pairs. Indentation (spaces) shows nesting:

YAML
name: CI
env:
  NODE_VERSION: "22"
  LANG: en_US

A sequence (a list) is written with a dash and a space for each item:

YAML
branches:
  - main
  - develop

The short flow form, branches: [main, develop], means exactly the same thing. Flow style is handy for short lists.

A scalar is a single value: a string, number, boolean or null. Strings usually need no quotes.

YAML
retries: 3          # number
fast: true          # boolean
note: hello world   # string "hello world"
empty:              # null

Mappings and sequences nest freely. A list of mappings is the shape of almost every pipeline file, because steps are a list and each step has named fields:

YAML
steps:
  - name: Install
    run: npm ci
  - name: Test
    run: npm test

Here is the rule that matters most: indentation is structure. Use spaces, never tabs. Use the same number of spaces (two is the convention) for each nesting level. A key that is one space off belongs to a different parent or makes the file invalid.

Comments

A # that starts a comment must be at the start of a line or follow a space. Everything after it is ignored. A # inside a quoted string, or glued to a word like abc#def, is ordinary text.

Multi-line strings

Shell scripts often need several lines. YAML has two block scalar markers for this, written after the key:

YAML
# Literal (|): keeps the line breaks as they are
run: |
  echo "Installing"
  npm ci
  npm test

# Folded (>): joins lines with spaces
description: >
  This sentence is written on two lines
  but becomes a single line.

Use | for scripts. Each line stays a separate command line, which is what a shell expects. Use > for long prose. By default a block scalar keeps one trailing newline. A trailing - (as in |-) removes it, and + keeps all trailing blank lines. Indent the block's lines consistently, and the block ends at the first line with less indentation.

Quoting traps

The famous traps all come from YAML guessing the type of an unquoted value.

  1. Colons followed by a space. In a plain (unquoted) value, : starts a new mapping, so run: echo build: done is an error. This also applies when part of the text is in quotes: run: echo "build: done" is still invalid, because the value does not begin with a quote. Quote the entire value (run: 'echo "build: done"') or use a block scalar (run: |).
  2. Version numbers. python-version: 3.10 is read as the number 3.1, and your job installs the wrong Python. Quote versions: "3.10". This one has bitten countless projects. A value like 3.12.1 has two dots, so it stays a string, but quote it anyway for consistency.
  3. The on/no problem. The older YAML 1.1 rules treat on, off, yes, no, y and n as booleans. Many libraries still follow them. GitHub's on: trigger key works in Actions, but some tools that read workflow files (for example, scripts using an older YAML library) see true instead. A country code NO for Norway famously turned into false in such files. Quote anything that is not meant to be a boolean.
  4. Special first characters. A value starting with *, &, !, %, @ or a backtick has a special meaning in YAML (aliases, anchors, tags, directives). Quote it. A leading { or [ starts a flow collection, and - starts a list item.
  5. A # after a space. run: echo #1 runs echo only, because #1 is a comment. Quote the value if you need the hash.

When in doubt, quote strings. "22" is always the string 22.

JS How a plain scalar is typed (YAML 1.1 vs 1.2 rules)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The row for 3.10 is the same under both rule sets: it becomes the number 3.1, losing the trailing zero. Only quotes preserve it. The rows for on, no and yes differ: older rules turn them into booleans.

This stand-in is a simplified model of how scalars are typed, not a complete YAML implementation. Real parsers also handle octal numbers, dates, hexadecimal and more.

Anchors, aliases and merge keys

YAML lets you name a block once with an anchor (&name) and reuse it with an alias (*name). A merge key (<<) copies the keys of an anchored mapping into another mapping, where explicit keys win. GitLab CI/CD supports all of this and uses it to share settings between jobs:

YAML
.defaults: &defaults
  image: node:22
  before_script:
    - npm ci

lint:
  <<: *defaults
  script:
    - npm run lint

test:
  <<: *defaults
  script:
    - npm test

Both jobs get the image and before_script from .defaults. Beware that merging is shallow: if a job defines its own before_script, it replaces the whole list instead of adding to it. GitLab also offers extends for the same purpose, and it is usually the better choice (see Includes, Templates and Environments). GitHub Actions did not support anchors for a long time; support arrived only recently, so check the current documentation before relying on them there. A more common GitHub approach to reuse is reusable workflows and composite actions.

Reading an indentation error

When a file will not parse, look in this order:

  1. Tabs. A single tab used for indentation is invalid. Configure your editor to insert spaces.
  2. Alignment. A step's keys (name, run) must line up under each other. The first key sits after - , so the following keys are indented by two more than the dash.
  3. A colon in a value. See trap 1 above.
  4. A missing space after a colon or a dash (key:value, -item).

Error line numbers are often a line or two after the real mistake, because the parser only discovers the problem when the next line does not fit.

A miniature YAML parser

Real parsers are long, but the core idea is short: look at the indentation of each line, decide whether it is a key or a list item, and recurse into the deeper lines. The following program implements a small subset: mappings, sequences, flow lists, quoted strings, comments, and the | and > blocks. It has no anchors, tags or nested flow collections. Run it and read the object it builds, then read the three error messages.

JS A tiny YAML subset parser

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Look at the steps array: each list item that starts with uses: or name: became an object, exactly as the dash-plus-keys layout suggests. The | block kept its line breaks, while the > block became one line. The three broken files show how the same problem produces an error message with a line number.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does python-version: 3.10 give you in a typical YAML parser?

    An unquoted 3.10 is typed as a number, and the trailing zero is lost. Quote versions: "3.10".
  2. 2. Which line is invalid YAML?

    The value starts with echo, so it is a plain scalar, and a colon followed by a space is not allowed inside it. Quote the whole value or use a block scalar.
  3. 3. You want each line of a script to stay on its own line. Which marker do you use?

    The literal block marker | keeps line breaks, which is what a shell script needs. The folded marker > joins lines with spaces.
  4. 4. How does YAML show that one key is nested under another?

    Indentation with spaces is structure in block-style YAML. Tabs are not allowed for indentation.
  5. 5. A job defines its own before_script after merging <<: *defaults. What happens to the list from the anchor?

    Merge keys are shallow and explicit keys win, so a key you set yourself replaces the merged value instead of adding to it.

Summary

  • YAML has mappings (key: value), sequences (- item) and scalars; indentation with spaces is the structure, and tabs are not allowed.
  • Use | for scripts that keep their line breaks and > for prose folded into one line.
  • Quote values that YAML would mistype: versions like "3.10", words like "no" or "on" that are not booleans, and anything with : or a leading special character.
  • run: echo "a: b" is invalid because the colon-space sits in a plain scalar; quote the whole value or use a block scalar.
  • Anchors, aliases and << reduce repetition in GitLab files, but merging is shallow; prefer extends where available.
  • Error lines are often one line after the real mistake, so check tabs, alignment, colons and missing spaces.

Next: Your First Workflow