A pipeline that turns green is not the same thing as a pipeline you can trust. Plenty of teams run a .gitlab-ci.yml that technically "works" but takes twelve minutes for a one-line change, redeploys to production on a plain push, or hides test failures behind a misconfigured job. Here is how to build a GitLab CI pipeline that holds up under real conditions, not just on the demo branch.
The concrete problem
Take a Node.js/NestJS application backed by PostgreSQL, deployed across several environments (staging, production). The requirement: every merge request runs lint, unit tests and integration tests against a real database; every merge to main builds a versioned Docker image and deploys it automatically to staging, then to production only on manual approval.
The common mistake is cramming everything into a single sequential job, with no caching, no clear separation between build, test and deploy, and no distinction between what should run automatically and what must stay an explicit human action.
Why a poorly designed pipeline degrades fast
Three mechanisms explain most slow or dangerous pipelines:
- No cache, or a badly scoped one: reinstalling
node_modulesor Composer dependencies on every job multiplies pipeline time by the number of jobs, even though GitLab CI ships native key-based caching. - Jobs that are not parallelized: lint, unit tests and integration tests have no dependency on each other but are often chained inside a single
stage, which needlessly serializes the developer's wait time. - Deployment not scoped by branch/environment: without explicit
rules:, a pipeline can deploy to production from any branch, which is the classic accidental-push disaster.
Diagnose the existing pipeline first
Before rewriting anything, GitLab gives you diagnostic tools that are easy to overlook:
# Detailed duration of each job in the latest pipeline on main
glab ci view --branch main
# Find jobs taking over 5 minutes across the last 20 pipelines on main
glab api "projects/:id/pipelines?ref=main&per_page=20" \
| jq -r '.[].id' \
| xargs -I{} glab api "projects/:id/pipelines/{}/jobs" \
| jq '.[] | select(.duration > 300) | {name, duration}'
This surfaces the real bottleneck (often dependency installation, or an integration test waiting on a service that was not ready yet) instead of optimizing at random.
A pipeline that is actually structured
Stages and cache
stages:
- build
- test
- deploy
variables:
npm_config_cache: "$CI_PROJECT_DIR/.npm-cache"
default:
image: node:20-alpine
cache:
key:
files:
- package-lock.json
paths:
- .npm-cache/
- node_modules/
install:
stage: build
script:
- npm ci --prefer-offline
artifacts:
paths:
- node_modules/
expire_in: 1 hour
A cache key based on package-lock.json avoids two common traps: a cache that never invalidates (stale dependencies used silently) and a cache invalidated on every run (no gain at all). npm ci instead of npm install guarantees a reproducible install from the lockfile, which matters in CI where reproducibility outweighs convenience.
Parallelizing the checks
lint:
stage: test
needs: ["install"]
script:
- npm run lint
unit-tests:
stage: test
needs: ["install"]
script:
- npm run test:unit -- --coverage
coverage: '/All files[^|]*\|[^|]*\s+([\d.]+)/'
integration-tests:
stage: test
needs: ["install"]
services:
- postgres:16-alpine
variables:
POSTGRES_DB: test_db
POSTGRES_USER: test
POSTGRES_PASSWORD: test
DATABASE_URL: "postgresql://test:test@postgres:5432/test_db"
script:
- npm run migrate
- npm run test:integration
The needs keyword (instead of relying on implicit stage ordering) lets these three jobs start as soon as install finishes, running in parallel instead of waiting for the previous stage to fully complete. The postgres service runs as a sidecar container reachable by its service name (postgres) from inside the job, which avoids mocking the database for integration tests that would otherwise lose most of their value.
Building a versioned Docker image
build-image:
stage: build
image: docker:24-cli
services:
- docker:24-dind
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
script:
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
Tagging the image with $CI_COMMIT_SHORT_SHA instead of latest is what makes a rollback actually possible: without a traceable tag, reverting to the previous production version means rebuilding from the previous commit instead of simply redeploying an image that was already tested.
Environment-gated deployment
deploy-staging:
stage: deploy
environment:
name: staging
url: https://staging.example.com
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
script:
- kubectl set image deployment/app app="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" -n staging
deploy-production:
stage: deploy
environment:
name: production
url: https://example.com
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
when: manual
script:
- kubectl set image deployment/app app="$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" -n production
The when: manual on deploy-production is the real safety barrier, not an informal convention ("we just avoid pushing to main on Fridays"). The environment: keyword also gives a deployment history per environment in the GitLab UI, which is useful for tracing which version runs where without digging through logs.
The tradeoffs worth naming
- GitLab's native cache vs a shared dependency registry (Verdaccio, Artifactory): per-job caching is simple but starts cold if runner infrastructure changes; a shared registry is more robust but adds a component to maintain. For a single team on a single project, the native cache is usually enough.
dind(Docker-in-Docker) vs kaniko:dindis simpler to configure but runs in privileged mode, which is a real attack surface on a shared runner.kanikobuilds images without privileges but comes with its own syntax and constraints to learn.- Manual vs automatic production deployment: full automation reduces friction but removes the last human safety net. A
when: manualgate combined with solid integration tests is usually the right tradeoff rather than picking either extreme.
When this pipeline is not enough
This setup covers a monolithic application or a small number of services well. It breaks down for a monorepo with several independent services: at that point you need rules:changes: to only build/test what actually changed, and likely an incremental build tool (Nx, Turborepo) alongside GitLab CI, or pipelines will take tens of minutes even for an isolated change.
Keeping the pipeline fast over time
A pipeline that is fast on day one degrades mechanically as the project grows: every new feature adds a test, every new test adds a few seconds, and nobody notices the drift as long as it stays gradual. Two practices prevent this without heroic discipline:
- An explicit duration budget per stage, checked automatically rather than eyeballed. GitLab can fail a job once it exceeds a threshold, turning silent drift into a visible alert on the merge request that introduced it, right when it happens.
- Runners sized for the actual workload profile, not the average one. An integration test suite that spins up a full PostgreSQL instance needs more RAM than a lint job; sharing a single runner type across every job wastes either time (undersized runner for heavy tests) or budget (oversized runner for lint).
integration-tests:
stage: test
needs: ["install"]
tags:
- docker-runner-highmem # dedicated runner, sized for postgres + migrations
services:
- postgres:16-alpine
script:
- npm run migrate
- npm run test:integration
timeout: 8m # fails explicitly instead of silently drifting
Takeaway
A trustworthy pipeline comes down to three decisions: a properly scoped cache so you are not paying the install cost on every job, explicit parallelization through needs so independent work is not serialized, and deployment rules that make production unreachable by accident. Everything else is just YAML syntax.
