Workflow Syntax and YAML Basics

Workflow Syntax and YAML Basics

A workflow file is a YAML mapping. GitHub interprets a small set of top-level keys such as name, on, permissions, env, defaults, concurrency, and jobs. YAML is concise, but indentation and data types matter; a misplaced space can change structure.

Core ideas

• on accepts one event, a list of events, or a mapping containing event-specific filters.
• jobs maps stable job identifiers to job configuration. The identifiers are used by dependencies and expressions.
• Expressions inside ${{ ... }} read contexts such as github, inputs, needs, matrix, secrets, and vars.
• env can be declared at workflow, job, or step scope; the narrowest declaration overrides broader values.

How it works

Validate syntax before merging with the editor schema or a workflow linter. Quote ambiguous YAML values, use spaces rather than tabs, and remember that workflow files must use .yml or .yaml inside .github/workflows. Expressions are evaluated by Actions, while shell variable expansion happens later on the runner.

Configuration example

name: Validate
run-name: "Validate ${{ github.ref_name }} by @${{ github.actor }}"

on:
  workflow_dispatch:
    inputs:
      mode:
        description: Validation mode
        type: choice
        options: [quick, full]
        default: quick

env:
  CI: "true"

jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - run: echo "Mode is ${{ inputs.mode }}"

Read the example from top to bottom: the trigger creates a run, the job requests a runner, and each step receives only the context configured for it. Adapt names, versions, permissions, and commands to the repository rather than copying production credentials or policies blindly.

Production guidance

• Keep job identifiers stable; changing one can break needs references and required-check configuration.
• Prefer explicit values and small files over clever YAML anchors or deeply nested expressions.
• Do not place secrets directly in YAML. Reference the secrets context at the narrowest step that needs it.

The chapter quiz follows this lesson and checks both the vocabulary and the operational decisions behind the configuration.