YAML GitHub Actions

GitHub Actions runs tasks automatically when something happens in a code repository. A task might run tests after every change, build an application, or publish a package. Workflow files written in YAML describe those tasks, which makes GitHub Actions a practical example of YAML at work.

Where Workflow Files Live

Create a folder named .github/workflows at the top of the repository. Every YAML file inside that folder defines one workflow. GitHub detects the files and runs them without any further registration.

A Minimal Workflow

name: Test Project

on:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: echo "Tests passed"

The file reads from top to bottom like a recipe. A push to the main branch starts a job called check, which runs on a Linux machine and performs two steps.

The Main Keys

Key	Purpose
name	Label shown in the GitHub interface
on	Events that trigger the workflow
jobs	Groups of steps that run on one machine
runs-on	Type of machine for the job
steps	Ordered actions inside a job
uses	Borrows a ready-made action
run	Executes a shell command

How the Pieces Fit

  Event (push)
      |
      v
  +-------------- Workflow --------------+
  |  Job: check  (Ubuntu machine)        |
  |    Step 1: checkout code             |
  |    Step 2: run tests                 |
  +--------------------------------------+
      |
      v
  Result: green check or red cross

Triggers

The on key accepts one event, a list, or a detailed mapping.

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:

This workflow runs on pushes to main, on every pull request, every Monday at 06:00 UTC, and on demand through a button in the interface. YAML 1.1 parsers read the bare word on as a boolean, yet GitHub handles it correctly as a key.

Several Jobs

Jobs run in parallel by default. Use needs to enforce an order.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building"
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

The deploy job waits until the build job succeeds. A failed build stops the pipeline.

Variables and Secrets

The env key sets variables. Secrets hold private values such as access tokens, and you create them in the repository settings, never in the file itself.

env:
  APP_MODE: production

steps:
  - name: Publish
    run: ./publish.sh
    env:
      TOKEN: ${{ secrets.PUBLISH_TOKEN }}

The expression in double curly braces reads the secret at run time. GitHub hides the value in logs.

Testing on Several Versions

A matrix repeats a job with different settings:

strategy:
  matrix:
    python: ["3.11", "3.12", "3.13"]
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python }}

Quotes protect the version strings from becoming numbers, a lesson from the numbers topic.

Tips for Clean Workflows

• Give every step a clear name so logs read well.
• Pin actions to a version tag.
• Keep secrets out of the repository.
• Validate workflow files with an editor extension or a linter before committing.

Reading the Results

Open the Actions tab of the repository to see each run. A green check means every step succeeded, and a red cross marks a failure. Click a run to view the log for each step, with timestamps and output from every command.

Failed runs usually point to a typo, a missing secret, or a test that needs attention. Fix the problem, commit the change, and the workflow starts again automatically. The re-run button repeats a run without a new commit, which helps when a temporary network problem caused the failure.

Reusable Building Blocks

Actions published by the community cover common chores such as installing languages, caching downloads, and uploading build results. Reference them with the uses key and pass settings through with. Review the publisher and the version before adopting any action in an important project.

Small, readable workflows are easier to fix. Add one job at a time and watch the results in the Actions tab of the repository.