GuideJul 9, 2026~8 min · intermediate

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.

StackGitLab CIrunnersDockerartifactsenvironments

The 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

A 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

The 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.

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 ↗