How to Design a CI Pipeline Step by Step
On this page
Four questions before designing a pipeline
Copying a pipeline from another project gives you their problems. Instead, answer four questions for your service:
- What must never reach
main? Code that doesn't build, failing tests, known vulnerable dependencies, leaked secrets. - How fast must feedback be? A good target is under 10 minutes for a pull request.
- What can run in parallel? Checks that don't depend on each other.
- What runs only on
main, or only nightly, instead of on every pull request?
A worked CI pipeline design
The service: a Node.js API with about 1,200 unit tests (2 minutes), 150 integration tests against PostgreSQL (4 minutes), a Docker image, and an E2E smoke suite (3 minutes).
Draft 1: everything in one job, in sequence. Install, lint, unit, integration, audit, build, E2E: about 13 minutes. A vulnerable dependency is only reported after 7 minutes of tests, and one slow step delays every result after it.
Draft 2: split by dependency.
PR opened
├─ lint + typecheck ─────┐
├─ unit tests ───────────┤
├─ dependency audit ─────┼─► build image ─► E2E smoke ─► mergeable
├─ secret scan ──────────┤
└─ integration tests ────┘The independent checks run side by side; the image is built once they pass, and the E2E smoke test runs against that image. The critical path is now integration (4 minutes) plus build (1 minute) plus E2E (3 minutes): about 8 minutes, with lint or audit failures reported within a minute or two.
Final decisions:
| Check | Pull requests | `main` | Nightly |
|---|---|---|---|
| Lint, typecheck, unit tests | Yes | Yes | |
| Integration tests | Yes | Yes | |
| Dependency audit, secret scan | Yes | Yes | |
| Build image | Yes | Yes, and push | |
| E2E smoke | Yes | Yes | |
| Full E2E suite, performance tests | Yes | ||
| Container image scan | Yes | Yes (new CVEs appear daily) |
Pipeline design principles
- Fail fast: cheap checks first, or in parallel, so most failures appear in the first two minutes.
- Build once: the image tested in E2E is the image deployed (Day 5).
- Parallelize independent work, and shard long test suites (Day 13).
- Make every gate meaningful. If a check never blocks anything and nobody reads its output, drop it or make it blocking.
- Same commands locally:
npm run lintandnpm testwork the same on a laptop as in CI, so developers can reproduce failures. - Required checks: mark the merge-blocking jobs as required in branch protection; leave informational ones optional.
Pipeline time budgets
Pipelines get slower one reasonable step at a time. Set a time budget (say 10 minutes for pull requests) and track it. When the pipeline exceeds it, treat that as a bug: cache dependencies (Day 12), shard tests, or move slow checks to main or nightly.
Check yourself
They don't depend on each other, so running them side by side shortens feedback and reports each failure as soon as it happens.
The image that passed E2E tests is then exactly the image that gets deployed, and you avoid spending time building twice. A separate build for deployment could differ in subtle ways.
Cache dependencies and Docker layers, shard or parallelize the slowest test suites, and move slow checks that rarely fail to post-merge or nightly runs. Measure first, so you work on the critical path.
Around 10 minutes. Beyond that, developers switch to other tasks while waiting, lose context, and batch more changes together to avoid the wait, which makes reviews harder and feedback slower.
Expensive, rarely failing checks such as full E2E suites, performance tests or long security scans, as long as failures on main are fixed immediately.