Workflow File Structure and YAML Syntax
What you'll learn: How to structure a GitHub Actions workflow file correctly using YAML syntax rules.
The Blueprint of Your Workflow
Every GitHub Actions workflow lives in a .github/workflows/ directory as a YAML file (e.g., ci.yml). Think of YAML as a blueprint format—clean, hierarchical, and human-readable. Unlike JSON with its curly braces, YAML uses indentation (spaces, not tabs) to show structure, making it easier to read but strict about formatting.
Basic YAML Structure for Workflows
A workflow file always starts with a name and follows a predictable hierarchy:
name: My Workflow
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Run tests
run: npm test
Key YAML Syntax Rules
Indentation matters: Use 2 spaces per level. Misaligned items break the workflow.
Key-value pairs: Written as key: value with a space after the colon.
Lists: Use hyphens (-) for arrays:
on: [push] # inline array
# or
on:
- push # multi-line array
- pull_request
Strings: Usually unquoted, but use quotes if values contain special characters (:, #, {).
Comments: Start with # and are ignored during execution.
Hierarchical Structure
Workflows nest concepts: jobs contain steps, which contain run commands or uses actions. Each level indents further right, creating a visual tree that mirrors execution flow.
Key Takeaway: GitHub Actions workflows are YAML files with strict indentation rules—master the 2-space hierarchy and key-value format to avoid syntax errors and build reliable pipelines.