Course contentsShow
← Cloud and Infrastructure
Lesson 1697 of 2,98935. GitHub ActionsFree lesson

Workflow File Structure and YAML Syntax

Understand the basic structure of a GitHub Actions workflow file and YAML syntax requirements.

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.