How GitHub Actions is organised

GitHub Actions runs automation in response to events in your repository. Before writing YAML, learn the vocabulary, because every error message uses it.

• Workflow: a YAML file in .github/workflows/. A repository can have many.
• Event (trigger): what starts a workflow: a push, a pull request, a schedule, a manual dispatch, a release and many more.
• Job: a set of steps that runs on one runner. Jobs run in parallel by default and can depend on each other with needs.
• Step: a single shell command (run) or a reusable action (uses).
• Runner: the machine that executes a job. GitHub hosted runners are fresh virtual machines for every job, with Linux, Windows and macOS options. You can also register self hosted runners.

A minimal workflow

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm test

Commit it, open a pull request and watch the Checks section. Each step's output is streamed live, and a failing step marks the job and the check red.

Fresh machines every time

Each job starts on a clean virtual machine. Nothing persists between jobs unless you pass it explicitly as an artifact or restore it from a cache. This makes builds reproducible, and it is also why the first npm ci in every job downloads dependencies, which we fix with caching later.

Where actions come from

actions/checkout and actions/setup-node are actions maintained by GitHub. Thousands more exist on the Marketplace, written by vendors and individuals. An action is code that runs with access to your repository and secrets, so choosing and pinning them carefully matters, a topic we treat seriously in section five.

Billing in brief

Public repositories get free minutes on standard GitHub hosted runners. Private repositories have a monthly allowance that depends on your plan, after which minutes are billed, with macOS and larger runners costing more per minute. Fast workflows are therefore also cheaper workflows.