Workflow Syntax Basics
What you'll learn: How to structure a GitHub Actions workflow file using the five essential YAML keys that define what runs, when, and where.
The Foundation of Every Workflow
Every GitHub Actions workflow file is written in YAML and lives in .github/workflows/. Think of it like a recipe: you need to name your dish, specify when to cook it, list the kitchen stations, and detail each preparation step.
The Five Essential Keys
name
The human-readable identifier for your workflow. This appears in the GitHub UI when workflows run.
name: Build and Test Application
on
Defines which events trigger the workflow. You've already learned about workflow events—this is where you specify them.
on: [push, pull_request]
jobs
Contains one or more jobs that execute as part of the workflow. Each job gets its own identifier.
jobs:
build:
# job configuration here
runs-on
Specifies which runner (GitHub-hosted or self-hosted) executes the job. This determines the operating system and environment.
runs-on: ubuntu-latest
steps
The actual commands and actions that execute sequentially within a job. Each step can run shell commands or use pre-built actions.
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Run tests
run: npm test
How They Work Together
These five elements form a hierarchy: workflows contain jobs, jobs run on specific runners, and jobs contain ordered steps. The on key determines when this entire chain executes.
Key Takeaway: The five core YAML keys—name, on, jobs, runs-on, and steps—form the skeleton of every GitHub Actions workflow, defining identity, triggers, execution environment, and actual work to be performed.