Blog
4 min read

What Is YAML? The Config Format Behind GitHub Actions and Docker Compose

YAML is the human-readable format used for config files like GitHub Actions workflows, Docker Compose and Markdown frontmatter. The syntax in five minutes — keys, lists, nesting, strings, multi-line text — and the indentation and "no" gotchas that break files.

If you've opened .github/workflows/ci.yml, docker-compose.yml, or the top of a Markdown blog post, you've seen YAML. It's a format for writing structured data — settings, lists, configuration — in a way that's easy for people to read. It's also easy to break with one wrong space.

The short version

YAML is a text format for data, like JSON, but designed for humans to read and write. It uses indentation instead of brackets, and has almost no punctuation.

The name stands for "YAML Ain't Markup Language". Files end in .yml or .yaml — both are fine.

The same data in JSON and YAML

JSON:

{
  "name": "reading-list",
  "port": 3000,
  "debug": false,
  "databases": ["postgres", "redis"]
}

YAML:

name: reading-list
port: 3000
debug: false
databases:
  - postgres
  - redis

Same data, less noise. In fact, YAML is (nearly) a superset of JSON — most JSON is also valid YAML.

The syntax in five minutes

Key-value pairs

name: reading-list
port: 3000

A space after the colon is required.

Nesting with indentation

database:
  host: localhost
  port: 5432

host and port belong to database because they're indented under it. Use spaces, never tabs. Two spaces per level is the common convention; what matters is consistency.

Lists

steps:
  - checkout
  - install
  - test

Lists of objects combine both:

services:
  - name: web
    port: 3000
  - name: worker
    port: 4000

Comments

# This is a comment
port: 3000  # so is this

Multi-line text

script: |
  npm ci
  npm test
summary: >
  This long sentence is folded
  onto a single line.

| keeps line breaks (great for shell commands); > folds lines into one.

Where you'll see YAML

The gotchas that break YAML files

1. Indentation mistakes

One space off and a setting silently belongs to the wrong parent — or the file fails to parse. Use an editor that shows indentation and validates YAML (VS Code does with an extension), and never mix tabs and spaces.

2. "Yes", "no", "on" and "off"

In older YAML (version 1.1, still used by many tools), unquoted yes, no, on and off are read as true/false. This is famously called "the Norway problem": a list of country codes containing NO turns Norway into false. GitHub Actions' on: key works only because the tool expects it.

Rule: quote strings that could look like something else.

country: "NO"
answer: "yes"

3. Numbers that should be strings

version: 1.10     # becomes the number 1.1
zip: 01234        # may lose the leading zero
time: 12:30       # may be read as a number in some parsers

Quote them: version: "1.10".

4. Special characters

A value starting with *, &, !, {, [, @, %, or containing : or # needs quotes:

title: "Step 1: install"
password: "abc#123"

5. Secrets in YAML files

Config files are committed to git. Never put passwords or API keys directly in them — reference secrets instead. In GitHub Actions that's ${{ secrets.MY_KEY }}. (Secrets management beyond .env files.)

Checking a YAML file

When something isn't working:

  1. Paste the file into a YAML validator or let your editor check it.
  2. Convert it to JSON (many online tools do this) to see how it's actually being read — the Norway problem becomes obvious.
  3. For GitHub Actions, the Actions tab shows workflow syntax errors.

The summary

  • YAML is a human-friendly data format, used mostly for configuration.
  • Indentation (spaces only) defines structure; - starts a list item; # starts a comment.
  • Quote anything that could be misread: "NO", "yes", "1.10", values with colons or #.
  • Don't put secrets in YAML files.

EasySpawn gives Claude Code a real server to run your workflows, Compose files and builds — so a YAML mistake shows up as an actual error it can fix. See how it works or join the waitlist.

Related: What Is JSON? · What Is CI/CD? · Claude Code GitHub Actions · Linters and Formatters Explained

Keep reading