What Is a YAML Multiline String? Explained

A YAML multiline string is a block scalar that lets you write text spanning several lines, controlling whether newlines are kept or folded into spaces.

Sooner or later a workflow step needs a multi-line script, and that is where YAML block scalars come in. YAML offers a couple of styles for writing long text across many lines, and the choice between them decides whether your line breaks survive. Getting this right is the difference between a shell script that runs and one that collapses into a single broken line.

What a multiline string is

A YAML multiline string, or block scalar, lets a single value span multiple lines using a leading indicator instead of quotes. The text continues as long as it stays indented under the key. This is how you embed a whole shell script or a long message as one YAML value.

Literal versus folded

The literal style (the pipe character) preserves every newline exactly as written, which is what you want for scripts where line breaks are commands. The folded style (the greater-than character) joins lines with spaces, turning your block into one long line - good for prose, wrong for scripts.

Chomping indicators

A trailing modifier controls the final newline: a plain block keeps one trailing newline, a minus strips trailing newlines (clip vs strip), and a plus keeps them all. These details rarely matter for a script but can matter when the exact bytes of the value are significant.

Multiline strings in CI

The most common use is a multi-line run step. You write the script under a literal block so each line is a separate command. Using the folded style here is a classic bug: the commands run smashed onto one line and fail in confusing ways.

A literal block script in CI

# A multi-line run step using a literal block
steps:
  - run: |
      echo "building"
      npm ci
      npm run build

Latchkey note

Multi-line run steps behave the same on Latchkey runners, so your existing literal-block scripts execute line by line exactly as they do on GitHub-hosted runners.

Key takeaways

A YAML multiline string (block scalar) lets one value span several indented lines.
Literal style (pipe) keeps newlines; folded style (greater-than) joins lines with spaces.
In CI, write multi-line run scripts as literal blocks so each line stays a separate command.