CI/CD Pipeline Rules

A CI/CD pipeline's value is proportional to how fast it gives feedback and how little a human has to remember to do manually — a slow pipeline gets skipped, and a deploy with manual steps is a deploy someone eventually forgets a step in.

Fast feedback ordering

• Order pipeline stages cheapest-and-most-likely-to-fail first: lint before test, test before build, build before deploy — a typo caught by lint in 10 seconds shouldn't wait behind a 5-minute build to be reported.
• Run fast, narrow checks (type-check, lint, unit tests) before slow, broad ones (integration tests, e2e, full production build) so the common failure case (a straightforward bug) is reported as fast as possible.
• Parallelize independent stages (lint and unit tests can usually run concurrently, not sequentially) where they don't depend on each other's output, to shorten wall-clock time without changing what's checked.

Fail fast

• Configure the pipeline to stop and report on the first failing stage rather than continuing through remaining stages after something's already known to be broken — continuing to run a slow build after lint has already failed wastes CI minutes and delays the failure signal for no benefit.
• Within a stage, prefer tooling that reports all findings in one pass (a linter listing every violation) over a runner that stops at the first individual failure — that trade-off is opposite to the cross-stage one: within one stage, more signal per run is worth more than stopping instantly.
• Make failures loud and specific (which check, which file, which line) in the pipeline output — a red pipeline with a generic "build failed" forces someone to dig through logs that a well-configured tool would have surfaced directly.

Caching dependencies

• Cache package manager dependencies (node_modules / the package manager's cache directory) keyed on the lockfile hash, so an unchanged lockfile reuses the cache and only a changed one triggers a fresh install — dependency installation is often the single slowest step in an otherwise fast pipeline.
• Cache build outputs/intermediate artifacts where the tooling supports incremental builds, but invalidate the cache key on anything that could make a stale cache produce wrong output (source hash, config hash, toolchain version) — a stale cache that silently reuses outdated output is worse than no cache.
• Verify cache hits actually happen (check pipeline logs) periodically — a caching config that silently stops matching keys (e.g. after a lockfile format change) degrades to the slow path without anyone noticing until someone investigates why CI got slower.

Secrets via the platform's store

• Store all secrets (API keys, deploy tokens, database credentials) in the CI/CD platform's dedicated secret store (encrypted, access-scoped), never in the repository, in a committed .env file, or hardcoded in a pipeline config file — a secret that reaches git history is compromised permanently, even if later removed, since it remains in history and in any fork/clone made before the removal.
• Scope secrets to the minimum set of pipelines/environments that need them — a deploy token for production shouldn't be readable by a pipeline that only runs on PRs from forks, where it could be exfiltrated by a malicious PR.
• Rotate secrets that a pipeline config change, a departed team member, or a suspected exposure could have compromised — don't treat secret rotation as a one-time setup step never revisited.

Deploy from main only

• Restrict production deploys to a single, protected branch (main/trunk) that only accepts changes through reviewed, CI-passing pull requests — allowing production deploys from arbitrary branches or from a developer's local machine bypasses every check the pipeline exists to enforce.
• Require the full pipeline (lint, test, build) to pass on that branch before the deploy stage runs — a deploy stage that runs regardless of upstream stage results defeats the entire point of having them.
• Protect the branch itself (required status checks, no force-push, no direct pushes) so "deploy from main" is actually guaranteed by branch protection rather than by convention that someone can accidentally bypass.

Rollback plan

• Know before you need it how to roll back a bad deploy — redeploy the previous known-good build/image, not just revert the commit and hope the next pipeline run finishes in time during an incident.
• Prefer deployment strategies that make rollback fast and low-risk (keeping the previous build artifact deployable, blue-green or immutable-release deploys) over ones where rollback requires rebuilding from scratch under pressure.
• Pair any migration that changes the database schema with a rollback plan for the app-level deploy — an app rollback that hits a since-migrated database schema which the older code can't understand turns a simple rollback into a second incident.

No manual production steps

• Every step needed to get code from merge to running in production should be in the pipeline, not in a runbook a human executes by hand — a manual step is a step someone eventually skips, does out of order, or gets wrong under the time pressure of an incident.
• If a step genuinely requires human judgment (an approval gate before a sensitive deploy), model it as an explicit approval gate within the pipeline, not as an undocumented "ping someone before you deploy" convention.
• Treat any deploy runbook with more than an approval click as a sign the pipeline is incomplete — the fix is automating the step, not documenting it more thoroughly.