ci-pipelines

CI Pipelines

The purpose of CI is to answer one question as fast and as truthfully as possible: is this change safe to merge? Every design decision — stage order, what runs in parallel, what blocks merge — should be judged against that question. A pipeline that is fast but lies (flaky, non-deterministic, skips real checks) is worse than no pipeline, because people stop trusting it and start merging past red.

A pipeline that takes twenty minutes but never lies beats one that takes two minutes and is wrong once a week.

A CI pipeline exists to produce a merge signal that is fast, deterministic, and trusted — in that order of what you sacrifice first.

For concrete GitHub Actions patterns — caching, matrix builds, SHA pinning, OIDC, reusable workflows — read references/github-actions.md.

1. Order stages cheapest-and-most-likely-to-fail first

Lint and type-check fail faster than unit tests, which fail faster than integration tests, which fail faster than end-to-end tests. Run them in that order and fail fast on the first red stage instead of running everything to completion. This isn't just about total wall-clock time — it's about the time a developer waits for the first useful signal, since that's when they context-switch back to the PR.

• Static checks first: formatting, linting, type-checking — seconds, and catch the most common mistakes.
• Unit tests second: no network, no containers, fully parallelizable.
• Integration/e2e last: slowest, most infrastructure-dependent, most prone to flakiness.

Done when: a developer gets their first CI failure signal in under two minutes for the common case (lint or unit test failure).

2. Pin everything the pipeline touches

A pipeline that produces a different answer on a re-run of the same commit is not a merge signal, it's a random number generator. Pin the CI runner image, the language/toolchain version, and every dependency via a lockfile (package-lock.json, poetry.lock, go.sum, Gemfile.lock). "Latest" tags for base images and unpinned action versions (uses: actions/checkout@v4 vs @sha256:...) are the two most common sources of a pipeline that passed yesterday and fails today for no code reason.