← All articlesInfra and cloud

Using GitLab CI/CD well

A well-built GitLab pipeline tests, builds and deploys on every push, hands-free. Here's how I structure a clean .gitlab-ci.yml: stages, cache, artifacts, environments and conditional deployment.

Julien Mauclair · ~8 min · intermediate
StackGitLab CIrunnersDockerartifactsenvironments

01The mental model

GitLab CI reads a .gitlab-ci.yml file at the root. It defines jobs, grouped into stages that run in sequence: a stage only starts if the previous one succeeded. Jobs run on runners — machines that execute your commands in a container.

joba unit of work (lint, test, build…)
stagea group of jobs running in parallel
runnerthe machine that runs the job
artifacta file passed from one stage to the next

02A complete pipeline

Three stages are enough for most apps: test, build, deploy. Cache avoids reinstalling dependencies in each job; artifacts carry the build.

.gitlab-ci.ymlYAMLCopy
# .gitlab-ci.yml — un pipeline en 3 stages
stages: [test, build, deploy]
variables:
NODE_ENV: test
cache: # reutilise node_modules entre les jobs
key: ${CI_COMMIT_REF_SLUG}
paths: [node_modules/]
test:
stage: test
image: node:20
script:
- npm ci
- npm run lint && npm test
build:
stage: build
image: node:20
script: [npm ci, npm run build]
artifacts: # passe le build au stage suivant
paths: [.next/]
deploy:
stage: deploy
script: ./scripts/deploy.sh
environment: production
only: [main] # ne deploie que depuis main

03The good practices

Cache & artifacts

Cache = what you rebuild (node_modules). Artifact = what you pass on (the build). Don’t confuse them.

Conditional deploy

only: [main] or rules: prod deploys only from the right branch, never from a feature branch.

Environments

Declare staging and production: GitLab tracks what’s deployed where, and enables one-click rollback.

Secrets as variables

Never a secret in the YAML: put them in masked CI/CD variables, in the project settings.

Worth noting

The same deploy script should run in CI and locally — that’s the principle of make a deployment boring.

04Sources & further reading

Sources & further reading
01GitLab — .gitlab-ci.yml keyword referenceThe complete YAML keyword reference: stages, script, artifacts, cache, environment, rules.↗02GitLab — Caching in GitLab CI/CDThe cache vs artifacts difference explained by GitLab, with key and fallback strategies.↗03GitLab — Environments and deploymentsDeclaring staging and production, tracking deployments and rolling back.↗04GitLab — Specify when jobs run with rulesThe modern replacement for only/except: conditions, variables and migration.↗05GitLab — CI/CD variablesMasked and protected variables: the right way to keep a secret out of the YAML.↗06GitLab — Pipeline architecturesBasic pipelines, DAG with needs and parent-child pipelines: when to pick which.↗07GitLab — RunnersGitLab-hosted or self-managed runners: what actually executes your jobs.↗
In short

A good GitLab pipeline is invisible: it tests and deploys without you thinking about it, and stops you cold when something breaks. Three stages, cache, artifacts, well-stored secrets — and you push with peace of mind.

GitLab CI/CD docs ↗
Julien MauclairJulien Mauclair is the co-founder and CTO of Klickbee, where he builds the agency’s websites, tracking and AI automations, and develops Klickbee Tracking. He also runs Stralya, which designs and runs AWS infrastructure for scale-ups. Before that, he built the entire AWS infrastructure of an e-commerce business, since sold.

Read next