Order checks so the cheapest and most likely failures surface first, express real dependencies with `needs`, run independent jobs in parallel, and budget the minutes between push and verdict.
The problem
A pull request takes 38 minutes to turn red. Lint runs after a 25-minute integration suite because the stages were added in the order somebody thought of them, so a typo that a 20-second check would have caught holds a runner for most of an hour. Engineers stop watching the checks, push more commits while the old run is still going, and the run queue grows. Stage order and dependencies decide how soon a failure becomes visible, regardless of how fast any single test is.
How it works
- Wall-clock time is the longest path through the `needs` graph, not the sum of the jobs. In the example workflow `lint` and `unit` start together, `build` waits for both, then `integration` and `e2e` run side by side. With illustrative durations of 2, 6, 4, 12 and 20 minutes the serial total is 44 minutes but the critical path is `max(2, 6) + 4 + max(12, 20) = 30`. Speeding up a job that is off the critical path changes nothing.
- Order checks by cost and by how often they fail: formatting, lint, type-check and unit tests first, anything that needs a built artifact or a running environment (integration, end-to-end) after `build`. The question for each stage is whether its failure makes the later stages pointless; add a `needs` edge only if it does.
- Per the GitHub docs, `needs` lists jobs that must complete successfully: if a job fails or is skipped, every job that needs it is skipped unless it uses a conditional such as `always()`. That is the fail-fast behaviour that saves runner minutes, and the reason report, cleanup and gate jobs need `if: always()` to still run.
- A job without `needs` starts immediately, so independent checks run in parallel by default and cost extra setup minutes (checkout, cache restore, toolchain install) once per job. Splitting a 10-minute job into five 2-minute jobs lowers latency only if setup is cheap relative to the work.
- The graph is validated before anything runs. Observed on actionlint 1.7.12: `job "c" needs job "missing" which does not exist in this workflow [job-needs]`, and for a loop `cyclic dependencies in "needs" job configurations are detected. detected cycle is "a" -> "b" -> "a" [job-needs]`. When both mistakes were present only the missing-job error was printed, so re-run after fixing the first.
- Stale runs waste the most minutes. A `concurrency` group keyed on the pull request (`ci-${{ github.workflow }}-${{ github.head_ref || github.run_id }}`) with `cancel-in-progress` set only for `pull_request` cancels the superseded run when a new commit arrives, while push runs on `main` fall back to a unique `run_id` group and always finish. Never cancel a deployment this way.
- `timeout-minutes` defaults to 360 per job (per the docs), so a hung test can hold a runner for six hours. Set it per job to a few times the usual duration so a hang becomes a red check in minutes.
- Measure two numbers separately: time to first failure and time to green. `gh run view RUN_ID --json jobs` exposes `startedAt`, `completedAt` and `conclusion` per job, enough to rebuild the critical path from history (not run here, no repository access). Choose a feedback budget such as ten minutes to the first verdict on a pull request; the figure is a team decision, not a standard.
Examples
Cheap checks first, build after both, slow suites side by side; superseded pull request runs are cancelled (actionlint 1.7.12 clean).
name: ci
on:
pull_request:
merge_group:
push:
branches: [main]
concurrency:
group: ci-${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
permissions:
contents: read
jobs:
lint:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v7
- run: make lint
unit:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v7
- run: make test-unit
build:
needs: [lint, unit]
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
- run: make build
integration:
needs: build
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- run: make test-integration
e2e:
needs: build
if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'run-e2e')
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
- run: make test-e2eLint the graph locally, then list per-job start and end times of a run to find the critical path.
# A broken dependency graph is rejected before any runner starts
actionlint .github/workflows/ci.yml
# .github/workflows/ci.yml:13:3: job "c" needs job "missing" which does not exist in this workflow [job-needs]
# Critical path from a finished run: one line per job, ordered by start time
RUN_ID=${1:?run id}
gh run view "$RUN_ID" --json jobs \
--jq '.jobs[] | [.startedAt, .completedAt, .conclusion, .name] | @tsv' | sortIn practice
- GitHub Actions — Jobs run in parallel unless linked by `needs`; `concurrency` and `cancel-in-progress` drop superseded runs, and `timeout-minutes` bounds hung jobs.
- GitLab CI/CD — Jobs in a stage run in parallel and stages run in order; `needs:` lets a job start as soon as the jobs it lists finish, so the pipeline becomes a DAG instead of strict stages.
- Buildkite — Pipelines are lists of steps in which `wait` steps and `depends_on` express the ordering, so cheap checks can gate the expensive ones.
- Nx — Computes a task graph from `dependsOn` and the project graph, then runs independent tasks in parallel, which is the same critical-path logic inside a build tool.
- Bazel — Executes the action graph with as much parallelism as dependencies allow, so only the longest chain of actions decides build latency.
Trade-offs
Pros
- Failures surface in minutes, so authors still have the change in their head
- Skipped downstream jobs save runner minutes on every red run
- A critical-path view shows which job is worth optimising and which is not
- Cancelling superseded runs keeps the queue short on busy branches
Cons
- Every `needs` edge serialises work and lengthens time to green when the earlier job passes
- Fail-fast reveals one failure per round trip, so a change with three problems costs three pushes
- Parallel jobs repeat checkout, cache restore and setup, raising total billed minutes
- Cancel-in-progress can cancel a run somebody wanted to read, and must never apply to deployments