part four · the ci/cd pipeline
The CI/CD Pipeline
Six stages, each catching a different chain level.
The pipeline is the chain's machinery for moving code from the developer's editor to production. The corpus pattern: the pipeline is structured into six stages, each of which catches a different level of chain mistake. Skipping a stage does not save time; it pushes the missed mistake further along, where it is more expensive.
The six stages
| Stage | Catches | Tools (typical) |
|---|---|---|
| 0 · Pre-commit | Trivial mistakes before they enter the repo | Husky, lint-staged, prettier, eslint, secrets scan |
| 1 · Build & lint | Compilation errors, type errors, lint violations | tsc, eslint, vue-tsc, vite |
| 2 · Unit & contract tests | Logic errors at the function/module level | Vitest, contract test runners |
| 3 · Integration & e2e | Wiring errors across modules; Gherkin scenarios | Playwright, Cypress, supertest |
| 4 · Visual regression | Unintended UI changes against Figma baselines | Chromatic, Percy, Lost Pixel |
| 5 · Security & dependency | Known CVEs, leaked secrets, license issues | npm audit, semgrep, gitleaks |
| 6 · Deploy & smoke | Deployment-time errors; basic post-deploy health | The deploy script, smoke check |
Six stages plus the pre-commit zero-stage. Seven gates. Each one has a specific job and a specific way to fail.
Pre-commit (stage 0)
Runs on the developer's machine before the commit lands. Catches:
- Style violations (prettier, eslint).
- Files that shouldn't be committed (secrets, large binaries).
- Type errors at the file level (sometimes — full typecheck waits for stage 1).
If pre-commit catches it, the commit doesn't enter the repo. This is the cheapest stage to catch anything. The corpus rule: never bypass pre-commit hooks. If they're slowing the team down, the hooks are wrong, not the discipline.
Stage 1 — Build & lint
Compiles the project. Type-checks. Lints across the whole codebase. Fast — under three minutes for a healthy project.
A red stage 1 means the change is structurally broken. No further stages run.
Stage 2 — Unit & contract tests
Runs the unit test suite. Runs contract tests against any API the project exposes.
Unit tests are scoped to a single function/module. Contract tests are the boundary tests — given this input, the function/API returns this output.
A red stage 2 usually means logic is broken. The story's Gherkin scenarios should be in this stage if they are unit-test-shaped.
Stage 3 — Integration & e2e
Runs the broader test suite. Spins up dependencies in containers. Executes the Gherkin scenarios as end-to-end browser tests.
This stage is the most expensive — sometimes 10–20 minutes for a healthy project. The corpus pattern: parallelise. A 20-minute serial run becomes a 4-minute parallel run.
A red stage 3 means the wiring is wrong. Modules that work alone don't work together. This is where amigos pays back its time investment.
Stage 4 — Visual regression
Compares rendered UI against approved baselines. Failures surface as visual diffs that the Designer reviews.
This stage catches the I didn't realise that change moved that pixel class of bug. It is also the stage that catches accessibility regressions, contrast changes, and RTL layout drift.
The baselines come from Figma — the named states from the Designer's frames. Every named state has a baseline. New visual states require a new baseline approval.
Stage 5 — Security & dependency
Scans dependencies for known vulnerabilities. Scans the diff for secrets. Checks license compliance for new dependencies.
A red stage 5 usually means don't merge yet, talk to security. Sometimes it means the world has learned a CVE since yesterday and our dependency is now flagged.
Stage 6 — Deploy & smoke
Deploys the build to the target environment. Runs a small post-deploy smoke check — the homepage returns 200, the API returns 200, the version banner matches.
A red stage 6 in production triggers automatic rollback. The pipeline knows the previous artifact and switches back.
Reading the pipeline
Each stage's failure has a different chain meaning:
| Stage red | Chain interpretation |
|---|---|
| 0–1 | A mechanical / hygiene gap. Cheapest fix. |
| 2 | A logic gap. The unit test should have caught it; sometimes the test is the gap (not the code). |
| 3 | A scope gap. The Gherkin or the wiring is wrong. Re-read the brief. |
| 4 | A design gap. The Designer-baseline pair didn't anticipate this change. |
| 5 | An external change in the world. Often nothing the team did. |
| 6 | A pipeline / environment gap. Often infrastructure. |
A team that reads pipeline failures by chain level builds a more reliable pipeline over time. A team that just reruns until it goes green builds a flaky one.
Environments
The corpus assumes three environments.
- Dev — the developer's local. Hot reload, mocks where appropriate, fast.
- Staging — production-shaped. Full pipeline runs here. The release gate (Part 6) verifies here.
- Production — the real thing. Smoke-tested by stage 6, monitored by Volume V machinery.
Each environment has a clear purpose. The corpus pattern: do not test in production unless the alternative was demonstrably impossible.