The Missing Manual
⌘K
← Back to guide / Phase 0
Updated Jun 19, 2026

Your First Pipeline (GitHub Actions)

You've seen the green check mark next to a pull request. You've also seen the red X — usually right when you were sure your change was fine — and felt that small drop in your stomach. Somewhere behind those marks, a machine you've never met ran your tests and made a verdict. This guide is about that machine and the file that tells it what to do.

By the end you'll have a real .github/workflows/ci.yml you understand line by line, the mental model to reason about any workflow you meet, and enough of the advanced moves — caching, matrices, secrets — to make CI fast and trustworthy instead of a mysterious gatekeeper.

📝 Terminology. CI is continuous integration: every time you push code, an automated build runs your checks (tests, linters, type-checks) so problems surface in minutes, not in someone else's afternoon. GitHub Actions is GitHub's built-in way to run CI (and more). If "what is CI even for" is fuzzy, read What CI/CD Does first, then come back here for the how.

How to read this

  • Want it to finally make sense? Read in order. Phase 1 installs the mental model, Phase 2 builds a real workflow on top of it, Phase 3 makes it fast and safe.
  • Already have a workflow and just need one concept? Jump straight to Phase 3: Beyond the Basics for caching, matrices, and secrets.

The phases

  1. The Anatomy of a Workflow — the mental model: events trigger workflows, made of jobs, made of steps, that run on a runner. The YAML structure decoded so it stops looking like magic.
  2. Building It Up — a real ci.yml that checks out your code, sets up your language, installs dependencies, and runs your tests — every line explained, with both a passing and a failing run log.
  3. Beyond the Basics — caching dependencies for speed, a build matrix to test multiple versions, secrets done safely, and required checks that block a bad merge.

Deliberately deferred to follow-up guides: deployment (the "CD" half — shipping to a server or registry), reusable/composite workflows, and self-hosted runners. This guide gets you a solid integration pipeline first; shipping comes once that's rock-solid.