Why Your CI Pipeline Keeps Failing (and the 5 Checks That Catch It)
Five checks that catch a red pipeline before it becomes a Friday plan.
A pipeline that is red for a new reason every day is not cursed. It is usually one of five boring problems, and the log already named it. Read the log before you rerun the job. Rerunning is how you spend twenty minutes confirming the same failure.
1. The runner is not your laptop
The job failed because a library, a CLI, or a file exists on your machine and does not exist on the runner. Pin the runtime in the workflow. Install from the lockfile. If the fix is "I installed it globally once", the pipeline will meet you again next week.
Check the image or the setup action version. actions/setup-node@v4 with an unpinned node-version: 20 is fine until 20 moves. Write the version you tested.
2. The test that only fails on the runner
A test that depends on the clock, the network, or the order of a map will pass locally and fail when the runner is slower. That is a flaky test. Quarantine it or fix the race. Do not add a retry: 3 and call the pipeline healthy. Retries hide the test you no longer trust, and then they hide a real failure next to it.
3. The lockfile you did not commit
npm install on the runner is a different tree from the one on your laptop if the lockfile is missing or stale. Commit it. Use npm ci, or the equivalent that refuses to renegotiate versions. Then scan that tree. A dependency advisory is a failed check you opted into, not a surprise outage.
4. The runner is out of disk, memory, or minutes
Timeouts and "no space left on device" are capacity, not a logic bug. Cache the dependency directory. Do not cache the test result. Delete build artifacts you already uploaded. If the job is legitimately larger than the runner, say so and use a bigger one. A pipeline that dies at minute 58 has been telling you this for a month.
5. The workflow file itself
A bad indent, a secret name that does not match the environment, a path that assumes a working directory the job never set. Lint the workflow if you have a linter. Otherwise read the file like you would read a script you are about to run on production, because that is what it is.
Required checks on the branch are the point. A green badge you can skip is decoration. If you would not merge it at 16:45 on Friday, the missing piece is a rollback, which is the CI/CD lesson, not a sixth motivational check.
The longer version is the CI/CD Pipeline Builder lesson: stages, artifacts, and a promotion path that can stop.