Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท GitHub Actions

Jobs, Steps, Runners and Matrices

Understand how GitHub Actions jobs, steps and runners fit together: needs, outputs, conditions, timeouts, concurrency and the build matrix, with a matrix expander to try.

A workflow is a set of jobs, and a job is a list of steps that share one runner. Getting this model right explains most of what you will see in the Actions tab: why two jobs cannot share files by default, why some jobs wait for others, and how one definition can fan out into dozens of test runs.

Jobs run in parallel unless you say otherwise

Every key under jobs: starts at the same time on its own runner. To order them, use needs:

YAML
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  deploy:
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
      - run: echo "Both passed, deploying"

Here lint and test run side by side, and deploy starts only after both succeed. If a needed job fails, the dependent job is skipped. You can override that with if: ${{ always() }} (run regardless) or if: ${{ failure() }} (run only when something failed, perfect for notifications).

flowchart LR
  A["lint"] --> C["deploy"]
  B["test"] --> C

Jobs without needs run in parallel; deploy waits for both.

Steps share a runner, jobs do not

Steps of one job run in order on the same machine, so a file created in step 1 exists in step 2, and environment variables persist if you write them to the special file $GITHUB_ENV. Jobs run on different machines. To pass a small value from one job to another, use job outputs:

YAML
jobs:
  version:
    runs-on: ubuntu-latest
    outputs:
      tag: ${{ steps.pick.outputs.tag }}
    steps:
      - id: pick
        run: echo "tag=v1.4.0" >> "$GITHUB_OUTPUT"

  announce:
    needs: version
    runs-on: ubuntu-latest
    steps:
      - run: echo "Releasing ${{ needs.version.outputs.tag }}"

A step writes name=value lines to the file named by $GITHUB_OUTPUT. The job lists which step outputs it exposes, and later jobs read them through needs.<job>.outputs.<name>. Outputs are for short strings. For files (build results, reports) use artifacts.

Runners: where the job executes

runs-on picks the machine. GitHub-hosted runners are fresh virtual machines with common tools preinstalled:

Label Operating system
ubuntu-latest Ubuntu Linux (the cheapest and fastest to start)
windows-latest Windows Server
macos-latest macOS on Apple silicon
ubuntu-24.04 A pinned Ubuntu version instead of "latest"

"latest" moves when GitHub updates the image, which can break a build one day. Pin a version when you need stability. Larger paid runners and self-hosted runners (machines you register yourself, with labels such as [self-hosted, linux, gpu]) exist for special needs. Public repositories get free hosted minutes; private repositories get a monthly quota that depends on the plan, and Windows and macOS minutes are billed at higher multipliers than Linux.

Be careful with self-hosted runners on public repositories: a pull request from a stranger could run code on your machine. Keep them for private repositories or isolated, disposable machines.

The build matrix

A matrix repeats one job for every combination of values. Instead of copying a job three times to test three Node versions on two systems, write:

YAML
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]
        exclude:
          - os: windows-latest
            node: 20
        include:
          - os: ubuntu-latest
            node: 24
            experimental: true
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci && npm test

The matrix produces the cross product of every list, then applies exclude (remove combinations) and include (add or extend combinations). fail-fast: false keeps the other combinations running when one fails; the default true cancels them to save time. Inside the job, ${{ matrix.os }} and ${{ matrix.node }} give the current values. A matrix may create at most 256 jobs, and max-parallel limits how many run at once.

The stand-in below expands a matrix the way the documentation describes. It is our own simplified model (it handles exclude and include in the common cases only), not GitHub's implementation.

JS Stand-in: matrix expander (not GitHub's engine)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Conditions, timeouts and concurrency

Three small keys prevent big headaches:

YAML
jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    timeout-minutes: 15
    concurrency:
      group: deploy-production
      cancel-in-progress: false
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh
  • if skips a job or step unless the expression is true. Inside if you may omit the ${{ }} wrapper.
  • timeout-minutes kills runaway jobs. The default is 360 minutes, far too long for most work, so set a realistic limit.
  • concurrency makes runs with the same group name queue up (or, with cancel-in-progress: true, cancel the older run). Use false for deployments so a newer push waits instead of killing a half-finished deploy, and true for test runs where only the latest commit matters.

You can also set defaults for every step, such as defaults.run.shell and defaults.run.working-directory, which is handy for monorepos where the code lives in a subfolder.

Debugging a job

When a step fails, read its log first; the last lines usually contain the real error. Add run: env | sort or run: ls -R to inspect the machine. Setting the repository secret ACTIONS_STEP_DEBUG to true turns on verbose logs, and re-running with Enable debug logging does the same for one run. Use continue-on-error: true on a step that is allowed to fail, and if: always() on cleanup steps that must run no matter what.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Two jobs have no needs. How do they run?

    Jobs start together on separate runners unless needs creates an order.
  2. 2. How do you pass a short string from one job to a later job?

    Jobs run on different machines; outputs are the supported channel for small values.
  3. 3. A matrix has os: [a, b] and node: [1, 2, 3]. With no include or exclude, how many jobs run?

    The matrix is a cross product: 2 x 3 = 6 combinations.
  4. 4. Why use concurrency with cancel-in-progress: false on a deploy job?

    Queueing protects an in-flight deployment, while cancel-in-progress true would stop it.

Summary

  • Jobs run in parallel on separate runners; needs creates order and outputs pass small values.
  • Steps within a job share one machine and run in sequence.
  • runs-on selects hosted or self-hosted runners; pin versions when stability matters.
  • A matrix fans one job out into many; use include, exclude, fail-fast and max-parallel to control it.
  • Set timeout-minutes and concurrency deliberately.

Next: Secrets, Variables and Expressions