YAML is a text-based data-serialization language designed to be directly readable and writable by people. It is a strict superset of JSON, but uses meaningful newlines and indentation rather than braces. In GitHub Actions, workflow definitions are YAML files stored under .github/workflows. section 3.1 section 1.2
Indentation defines structure, so whitespace is part of the configuration. YAML files use the .yml or .yaml extension; GitHub workflows use UTF-8. Comments begin with # and can appear on their own line or after a value, which helps document workflow intent without changing behavior. section 3.1.1
Use YAML’s basic forms to express workflow configuration:
- Write scalar key-value pairs such as integers, floats, strings, Booleans, null values, and timestamps. Quote keys or values when special characters or type interpretation would otherwise cause trouble. section 3.1.2
- Use maps for nested named values, with indentation representing parent-child structure. JSON-style inline maps are also valid. section 3.1.2
- Use sequences for ordered items, placing a dash before each item; inline JSON-style lists are an alternative. section 3.1.2
- Use a pipe literal block for multiline strings when embedding scripts or text that must retain line breaks and empty lines. section 3.1.2
A minimal workflow job
A workflow can declare jobs, select a runner, and list sequential steps. Here, the job runs on ubuntu-latest and executes a shell command. Higher-level keys such as name, on, and jobs begin at the same indentation level; nested job and step details are indented beneath them. section 2.2 section 1.2
Listing 3.1 Assigning basic scalar types to variables in YAML
integer: 42 float: 42.0 string: a text value boolean: true null value: null datetime: 1999-12-31T23:59:43.1Z
This listing contrasts common scalar forms, including numeric, string, Boolean, null, and datetime values, making YAML type interpretation visible before using values in workflow configuration. section 3.1.2
For workflow authoring, formatting affects execution: triggers initiate workflows, jobs may run in parallel unless dependencies chain them, and steps within a job run sequentially. Use editor autocomplete and validation feedback to maintain valid structure while adding triggers and jobs. section 1.2 section 2.2
