Pipeline & Operations · master area
CI/CD Pipeline
Seven stages, each catching a different chain level. Pre-commit → build → unit → integration → visual → security → deploy. The chain of catches.
Owners: Tech Lead, DevOps Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: The pipeline catches a different chain level at each stage.
Where it lives in the chain
- How We Build · The Pipeline — three environments, trunk-based
- How We Build · Commit discipline and the chain of catches — seven stages
The seven stages
| Stage | Catches | Chain level |
|---|---|---|
| Pre-commit | Format, lint, secrets | Execution (developer-side) |
| Build | Syntax, types, missing imports | Execution |
| Unit tests | Logic errors, scenario coverage | Execution / Scope |
| Contract tests | API boundary drift | Architecture |
| Integration tests | Wiring, end-to-end flow | Architecture / Scope |
| Visual regression | Silent design drift | Design / Scope |
| Security (SAST/SCA/secrets) | Code-level vulnerabilities, leaked secrets | Operation |
A failure at each stage means a different conversation. The team treats the stage that fails as the diagnostic — "this kept failing at integration" means the wiring is fragile; "this kept failing at unit" means the developer's mental model is off; "this kept failing at visual" means the design system is drifting.
How to do this
- Run every stage on every PR. Not selectively. Selective runs train teams to ignore the deselected stages.
- Fail fast. Order the stages by how cheap they are to run — pre-commit (instant), build (seconds), unit (under a minute), integration (a few minutes), visual (with snapshots), security (minutes). When stage 2 fails, stages 3–7 don't run.
- Make the failure legible. Each stage's failure points at the file, the line, the assertion. "Build failed" with no context is a pipeline nobody can fix.
- Keep the full run under 15 minutes. Beyond that, the team stops trusting the pipeline as feedback and starts deferring.
What good practice looks like
The pipeline is a living document of the team's chain-of-catches. When the wallet bug shipped, the postmortem added a contract test (new stage entry). When the JWT outage shipped, the postmortem added a token-compatibility smoke test (new stage entry). Every postmortem either adds to the pipeline or sharpens an existing stage.
The pipeline that lasts is the pipeline that learns. A static pipeline ages into noise; a curated pipeline accumulates chain wisdom.
Related crafts
- Pre-Commit Hooks — stage zero
- Code Review — the human stage
- Environment Management — where stages run