CI/CD pipeline design that a team will still understand in a year
Pipelines should produce an artefact you can promote. Everything else is ceremony that needs a reason.
A useful pipeline has a short story: take this commit, prove it, produce a thing, put that thing in an environment. Many pipelines instead accumulate every check anyone has ever requested, plus a deploy script that still needs a human to finish the last three steps.
Build once
If staging and production are built from different commits or different “latest” tags, you are not testing the thing you will ship. Produce an immutable artefact. Promote it. The pipeline that deploys production should not compile the application again.
Match ceremony to risk
A documentation change does not need the same gates as a schema migration. Branch protections, mandatory reviewers, and change tickets should scale with blast radius. When every change is treated as a crisis, people route around the process.
- Keep the fast feedback — unit tests, lint, compile — near the author.
- Run expensive suites on the artefact, on a schedule or on the path to production.
- Make rollback a pipeline, not a memory of which previous tag was good.
Secrets and identity
Deploy roles should be short-lived and scoped. A long-lived key in a variable store is a future incident. If a compliance process needs evidence, generate it from the pipeline instead of asking an engineer to screenshot a console.
If only one person can debug the pipeline, you have a single point of failure that happens to be written in YAML.
Common questions
What are CI/CD pipeline best practices?
Keep fast checks (compile, lint, unit tests) close to the author; build one immutable artefact and promote it; run slower suites on that artefact before production; match approval gates to risk; use short-lived, scoped deploy credentials; and make rollback an automated, rehearsed path.
Why should you build once and promote the artefact?
If staging and production are built separately, you are not testing the thing you ship. Promoting a single immutable artefact guarantees that what passed testing is exactly what reaches production, and makes rollback a matter of redeploying a previous artefact.
This article supports our DevOps engineering services. If the situation it describes is familiar, tell us about the systems involved.
