Workflows

~11 min · workflow, yaml, primitive

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

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

The outermost unit

A workflow is the outermost unit in GitHub Actions. It's a single YAML file in .github/workflows/ that describes when something runs and what runs. One workflow can have many jobs; one repo can have many workflows.

Three things every workflow has:

name — what shows up in the Actions UI. Optional but kindly.
on — the events that trigger this workflow.
jobs — a map of named units of work, each running on a runner.

The file extension is .yml or .yaml; either works. Filename is free-form (it shows up in URLs but isn't otherwise referenced from inside).

Conventions worth following

One workflow per concern — ci.yml, release.yml, nightly.yml. Don't pile every job into one.
Filename matches the workflow name (e.g. name: ci → ci.yml). Saves grep time later.
Keep workflows under ~200 lines. Past that, factor jobs into reusable workflows or composite actions (later in the quest).

Code

A complete minimal workflow·yaml

# .github/workflows/ci.yml
name: ci

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Echo something
        run: echo 'hello world'

External links

GitHub — Workflow syntax reference

Exercise

Create .github/workflows/hello.yml in any repo. Make it run on push, with one job that does echo 'hello world'. Push it. Watch it turn green in the Actions tab. Delete it after.