Jobs, matrix, and reuse: the DAG, fan-out limits, and reusable-workflow nesting

Jobs are a DAG, not a script

Most CI cost and latency problems trace back to not modeling the job graph deliberately — either everything runs sequentially when it didn’t have to, or everything runs in parallel when it needed ordering. Understanding the DAG is understanding where to fix both.

Jobs run in parallel by default; needs: draws the dependency edges that serialize them into a DAG:

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact: ${{ steps.pack.outputs.name }}
    steps: [ ... ]
  test:
    needs: build               # waits for build, reads its outputs
    runs-on: ubuntu-latest
  deploy:
    needs: [build, test]       # waits for both
    if: ${{ github.ref == 'refs/heads/main' }}
    timeout-minutes: 15        # kill a hung deploy, don't burn 6h

Each job runs on a fresh runner with no shared filesystem — that is why data moves between jobs through outputs (small strings) or artifacts (files), never through disk. A job inherits nothing from another’s working directory. Two production controls live at this level: timeout-minutes (default is a generous 360 minutes / 6 hours per job — far too long for most work, so set a real ceiling or a hung step burns hours of runner time) and if: conditions that gate whole jobs. needs also propagates failure: if build fails, test and deploy are skipped — unless a downstream job opts into running anyway with if: ${{ always() }} or if: ${{ !cancelled() }}.

Matrix: one job definition, many legs

strategy.matrix expands a single job into one leg per combination — the Cartesian product of every dimension:

strategy:
  fail-fast: false       # don't cancel siblings when one leg fails
  max-parallel: 6        # at most 6 legs run concurrently
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [18, 20, 22]
    include:
      - { os: ubuntu-latest, node: 22, coverage: true }  # add/augment a leg
    exclude:
      - { os: macos-latest, node: 18 }                   # drop a combination

The numbers that govern cost and behavior:

• It multiplies. 3 os × 3 node = 9 legs; adding any third dimension multiplies again. This is the Hook’s blow-up — a matrix is the easiest place in Actions to 10× your bill by accident.
• fail-fast (default true) cancels all in-progress and queued legs the moment one fails — fast feedback but you lose the full failure picture. Set false to see every failing combination, at the cost of paying for them all.
• max-parallel caps how many legs run at once; without it, legs run as concurrently as your runner concurrency limit allows (and a matrix is capped at 256 legs per workflow run).
• include/exclude are the precision tools: exclude removes a generated combination; include adds a one-off leg or augments an existing one with extra keys — the way to get curated coverage instead of a blind grid.

Together these four knobs mean you can always recover from a matrix that blew up: cap the burn with max-parallel, trim the product with exclude/include, and decide whether you want fast-fail feedback or the full picture with fail-fast. Without max-parallel on a matrix you haven’t thought through, a single new dimension can turn a manageable 9-leg suite into an 80-leg runner fire overnight.

Reusable workflows: factor the pipeline

When the same build-test-scan sequence appears in twenty repos, copy-paste rots. A reusable workflow is a workflow with on: workflow_call that other workflows invoke as a single job:

# .github/workflows/build.yml  (the reusable workflow)
on:
  workflow_call:
    inputs:
      node: { type: string, required: true }
    secrets:
      token: { required: true }

# caller
jobs:
  ci:
    uses: my-org/ci/.github/workflows/build.yml@v2   # pin to a tag/SHA
    with: { node: "20" }
    secrets: { token: ${{ secrets.NPM_TOKEN }} }

The hard limits worth memorizing: a call chain can nest up to 4 levels deep (a reusable workflow calling another, and so on — the 4th-level workflow may not itself call a reusable workflow), and a single workflow file may reference at most 20 unique reusable workflows across the whole tree. Pin the uses: reference to a tag or SHA, never a moving branch, for the same supply-chain reason you pin actions — @main lets the called workflow change under you. Secrets are not inherited automatically; you either pass them explicitly under secrets: or forward all with secrets: inherit. This is how large orgs keep one audited pipeline definition and call it everywhere, instead of twenty drifting copies.