GitHub Actions YAML Basics

Every GitHub Actions workflow lives in a YAML file. YAML is a plain text format that stores settings as labels and values. One misplaced space can stop an entire workflow, so a solid grip on the rules saves hours of frustration.

YAML in Simple Words

Picture a neatly organized shopping list. Each category sits on the left, and the items belong underneath with a small indent. YAML works the same way. Position on the line tells the computer which item belongs to which group.

Key-Value Pairs

A key is a label. A value is the information stored under that label. A colon followed by a space joins them.

name: Build Website
runs-on: ubuntu-latest

The space after the colon is mandatory. The text name:Build without a space does not work.

Indentation Rules

Indentation shows ownership. A line indented under another line belongs to it. Use two spaces for each level and avoid the Tab key, because YAML rejects tab characters.

+----------------------------+
| jobs:                      |   level 0
|   build:                   |   level 1 (belongs to jobs)
|     runs-on: ubuntu-latest |   level 2 (belongs to build)
|     steps:                 |   level 2 (belongs to build)
|       - run: echo Hi       |   level 3 (belongs to steps)
+----------------------------+

Lists

A dash starts each item in a list. Workflow steps always use lists because a job runs many steps in order.

steps:
  - name: Say hello
    run: echo "Hello"
  - name: Say goodbye
    run: echo "Goodbye"

Short List Style

Square brackets write a list on one line. Branch names often use this style.

branches: [ main, develop ]

Nested Maps

A key can hold other keys instead of a single value. Nesting builds the tree structure that GitHub reads from top to bottom.

on:
  push:
    branches:
      - main

Multi-Line Text

Long shell commands need more than one line. The pipe symbol keeps every line break exactly as written.

run: |
  echo "Installing tools"
  npm install
  npm test

The greater-than symbol folds lines into a single long line. Use it for long sentences, not for commands.

Comments

A hash symbol starts a comment. GitHub ignores everything after it on that line. Comments explain why a setting exists, which helps teammates and your future self.

# Runs only on the main branch
branches: [ main ]

Quoting Values

Quotes protect values that YAML might misread. A version number like 3.10 loses its trailing zero when unquoted because YAML treats it as the number 3.1.

python-version: "3.10"
message: "Build finished: success"

Quote any value that contains a colon, a hash symbol, or a leading special character such as an asterisk.

Visual Map of a Workflow File

name: Demo                  <- label for the workflow
on: push                    <- trigger
jobs:                       <- group of jobs
  test:                     <- one job
    runs-on: ubuntu-latest  <- machine type
    steps:                  <- list of steps
      - run: echo Done      <- one step

Common Mistakes

Mistake	Result	Fix
Tab characters	Parsing error	Use two spaces
Missing space after colon	Value ignored or error	Add one space
Uneven indentation	Wrong ownership	Align siblings exactly
Unquoted version numbers	Wrong version installed	Wrap in quotes

Tools That Catch Errors Early

The GitHub web editor underlines YAML errors as you type. Code editors such as Visual Studio Code show indentation guides and highlight broken structure. A YAML linter extension adds even stricter checks before you commit.

Practice Exercise

Write a small file that holds a name, a list of three fruits, and a nested group called address with two keys. Check that the indentation lines up. Break one rule on purpose and read the error message. Seeing the message once makes real errors easy to recognize later.