What Is a Heredoc in YAML? Explained

A heredoc in YAML is a shell here-document written inside a YAML multiline block, letting a CI step feed a chunk of text to a command.

A heredoc is a shell feature for feeding a block of text to a command, and people often want one inside a YAML run step - to write a config file, pipe a script into a tool, or pass a SQL block. Combining a shell heredoc with YAML block scalars works well, but the indentation and variable-expansion rules of both layers can trip you up.

Heredoc plus YAML block

A heredoc starts a block of input that ends at a chosen marker word. Inside a YAML run step you write the heredoc within a literal block scalar so the shell sees the lines verbatim. The YAML layer preserves the newlines; the shell layer consumes them as heredoc input.

Indentation interplay

Two indentation systems stack here: YAML requires the whole block indented under run, while the shell heredoc closing marker must match its own rules. Using the dash form of the heredoc operator lets you indent the body with tabs for readability, but spaces will not be stripped - a frequent source of "marker not found" errors.

Quoting the marker controls expansion

Whether shell variables inside the heredoc are expanded depends on the marker. An unquoted marker expands variables and command substitutions; a quoted marker passes the text through literally. Choosing wrong means either an unexpanded literal or an accidentally interpolated value.

Heredocs in CI

A common pattern is writing a config file from a run step using a heredoc, often combined with the GitHub Actions multiline output or environment-file syntax, which itself uses a heredoc-style delimiter to safely pass multi-line values between steps.

A heredoc in a run step

# Heredoc inside a YAML run block to write a file
steps:
  - run: |
      cat > config.yml <<'EOF'
      server: prod
      retries: 3
      EOF

Latchkey note

Heredocs and the multiline environment-file syntax run identically on Latchkey runners, so patterns like writing a config file or passing a multi-line job output work without any changes.

Key takeaways

A heredoc in YAML is a shell here-document written inside a literal block scalar in a run step.
YAML indentation and the heredoc closing-marker rules stack, so indentation mistakes are common.
Quoting the heredoc marker decides whether shell variables inside it are expanded or left literal.