GitHub Actions: continuous integration
Every pull request on your team is checked by a robot before a person reviews it. This lesson opens up that robot: what triggers it, where it runs, how jobs and steps fit together, how caching and secrets work, and how to read a red X. Then you write a complete CI workflow for a TypeScript project and lint it.
By the end you can
- Explain events, workflows, jobs, steps and runners, and how they connect
- Read any workflow file line by line, including
needs, a matrix, caching and artifacts - Find the failing step in a red run in under a minute, and re-run it
- Write and lint a CI workflow for
partner-api: lint, test on two Node versions, build - Make CI a required check on pull requests without the common traps
The everyday picture
At the distribution centre, every truck from a supplier is checked before its cartons reach the shelves. A checker opens a sample, counts the cartons against the goods received note (GRN), checks expiry dates and scans the barcodes. She uses the same checklist for every truck, no matter who the supplier is or how much of a hurry the store is in. If a carton fails, the whole pallet waits on the side with a red tag, and the supplier is told exactly which check failed.
Continuous integration (CI) is that checker for code. Every push and every pull request goes through the same checklist (lint, tests, build) on a clean machine, and the result appears on the PR as a green tick or a red X with the exact failing step. GitHub Actions is GitHub's built-in system for running those checklists.
Events, workflows, jobs, steps and runners
Five words explain all of GitHub Actions. Learn how they connect and every workflow file becomes readable.
- A workflow is a YAML file in
.github/workflows/, such asci.yml. It says when to run (on:) and what to run (jobs:). - An event starts it: a
push, apull_requestbeing opened or updated, aschedule, or a manualworkflow_dispatchbutton. - A job is a group of steps that runs on one machine. Jobs in a workflow run at the same time unless one says it
needsanother. - A step is one item in a job, run in order. It is either a shell command (
run: npm test) or a ready-made action (uses: actions/checkout@v7). - A runner is the machine that runs a job.
runs-on: ubuntu-latestasks for a GitHub-hosted Linux virtual machine; for private repositories that is 2 CPUs, 8 GB of RAM and 14 GB of disk.
Here is what happens when you push a commit to a PR. GitHub reads every workflow file in that commit and finds the ones whose on: matches the event. Each match becomes a workflow run. Every job in the run waits for a runner. The runner is a brand-new virtual machine: it starts empty, runs the job's steps one by one, reports the result, and is deleted. Nothing is left over for the next job. That is why every job begins with checkout and install, and why "it passed on my laptop" means little: CI proves the change works on a clean machine.
A step fails when its command exits with a non-zero code (see The terminal without fear). When a step fails, the remaining steps in that job are skipped and the job fails. Every job reports a check on the commit, named after the job, and the PR shows them all in its Checks tab (see Pull requests and code review).
Quick check
A workflow has three jobs, lint, test and audit, and none of them says needs. How do they run?
Jobs are parallel by default; only needs creates an order. The order in the file decides nothing, which surprises people who read a workflow top to bottom like a script.
ci.yml. Lint and the two matrix test jobs start at the same time on separate fresh machines; build waits because it needs them. Each job reports one check, so the PR shows four. A ruleset can require them before merge (see Branching strategies, releases and versions).