Workflow YAML — Anatomy

~13 min · yaml, syntax, anatomy

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

The full top-level shape

You've seen the pieces. Here's the full top-level shape of a workflow file, in the order GitHub expects:

name — display name.
run-name — per-run name (template-driven, optional).
on — events.
permissions — what the GITHUB_TOKEN can do.
env — workflow-level env vars.
defaults — default shell, working dir.
concurrency — cancel-in-progress group.
jobs — the actual work.

Commonly missed fields

permissions — by default, GITHUB_TOKEN is overly permissive. Set permissions: read-all at workflow level and override per job to enforce least-privilege.
concurrency — without it, every push starts a new run. With it, you can cancel in-progress runs on the same branch / PR.
defaults.run.shell — explicitly set bash on Linux/macOS if your scripts need bash-isms (Mac default sh can surprise you).

Code

Production-grade workflow header·yaml

name: ci
run-name: ci on ${{ github.actor }} / ${{ github.head_ref || github.ref_name }}

on:
  pull_request: {}
  push:
    branches: [main]
  merge_group: {}

permissions: read-all

env:
  PYTHON_VERSION: '3.12'
  NODE_VERSION: '22'

defaults:
  run:
    shell: bash

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    permissions:
      contents: read
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Python $PYTHON_VERSION, Node $NODE_VERSION"

External links

GitHub — Assigning permissions to jobs

Exercise

Take an existing workflow and add three things at the top level: permissions: read-all, concurrency: with cancel-in-progress, and defaults.run.shell: bash. Push and confirm runs still pass.