Quand j’ai commencé à construire des images Docker pour mes projets clients, ma première réaction a été de pousser tout sur Docker Hub. Rapide, connu, universel. Mais ça ne tient pas longtemps en production : les images privées sont payantes au-delà d’une certaine limite, la visibilité par défaut est publique si on n’y fait pas attention, et Docker Hub a connu plusieurs incidents notables ces dernières années.

J’utilise GitLab pour mes repos, et GitLab embarque une registry Docker complète, gratuite, intégrée au CI/CD. Autant en profiter. Dans cet article, je te montre comment je procède de A à Z : création du repo, Dockerfile, commandes de build et push, pipeline automatique, et gestion des accès.

Pourquoi utiliser la registry GitLab plutôt que Docker Hub

Docker Hub reste la référence pour les images publiques officielles (Nginx, PostgreSQL, Node.js…). Mais pour tes propres images, les limites arrivent vite :

La registry GitLab, c’est quoi ? C’est une registry Docker OCI-compatible intégrée directement dans chaque projet GitLab. Gratuite sur gitlab.com (dans les limites de stockage du compte), sans restriction de repos privés, et connectée nativement au CI/CD. Mes images restent dans le même endroit que mon code.

Prérequis

Créer un repo GitLab avec la registry activée

Sur gitlab.com, crée un nouveau projet : New project > Create blank project. Donne-lui un nom (ex: mon-app), choisis le niveau de visibilité (Private pour les projets clients), et valide.

La registry Docker est activée par défaut sur chaque projet. Tu peux la trouver dans le menu latéral : Deploy > Container Registry. L’URL de ta registry suivra ce format :

registry.gitlab.com/[namespace]/[projet]

Par exemple, si ton namespace GitLab est mon-groupe et ton projet mon-app :

registry.gitlab.com/mon-groupe/mon-app

Écrire un Dockerfile minimal

Pour l’exemple, je pars sur une application Node.js simple. Le principe est identique pour Python, Go, PHP ou n’importe quel runtime.

# Dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

USER node

CMD ["node", "server.js"]

Ajoute aussi un fichier .dockerignore pour ne pas copier les fichiers inutiles :

.git
node_modules
.env
*.md
tests/
coverage/

Build, tag et push vers registry.gitlab.com

La séquence est toujours la même : build, tag avec l’URL complète de la registry, login, push.

1. Authentification sur la registry

docker login registry.gitlab.com

GitLab te demande ton nom d’utilisateur et un token. N’utilise pas ton mot de passe GitLab – crée un Personal Access Token (Settings > Access Tokens) avec le scope write_registry.

2. Build de l’image avec le bon tag

docker build -t registry.gitlab.com/mon-groupe/mon-app:1.0.0 .

Je taggue toujours avec un numéro de version explicite. En plus, j’ajoute souvent :latest pour simplifier les déploiements :

docker build -t registry.gitlab.com/mon-groupe/mon-app:1.0.0 \
             -t registry.gitlab.com/mon-groupe/mon-app:latest .

3. Push vers la registry GitLab

docker push registry.gitlab.com/mon-groupe/mon-app:1.0.0
docker push registry.gitlab.com/mon-groupe/mon-app:latest

Une fois poussée, tu retrouves l’image dans l’interface GitLab sous Deploy > Container Registry. Tu peux vérifier les layers, les tags, la date de push et la taille de chaque image.

Automatiser avec .gitlab-ci.yml

Le vrai gain de la registry GitLab, c’est l’intégration CI/CD. À chaque commit, le pipeline build l’image et la pousse automatiquement, sans que tu aies à gérer les credentials manuellement, car GitLab injecte les variables nécessaires dans chaque job.

# .gitlab-ci.yml
stages:
  - build

variables:
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
  IMAGE_LATEST: $CI_REGISTRY_IMAGE:latest

docker-build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $IMAGE_TAG -t $IMAGE_LATEST .
    - docker push $IMAGE_TAG
    - docker push $IMAGE_LATEST
  only:
    - main
    - tags

Optimiser avec le cache des layers

Pour accélérer les builds sur le CI, j’utilise le cache de layers Docker via BuildKit :

docker-build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
    DOCKER_BUILDKIT: "1"
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - |
      docker build \
        --cache-from $CI_REGISTRY_IMAGE:latest \
        --build-arg BUILDKIT_INLINE_CACHE=1 \
        -t $IMAGE_TAG \
        -t $IMAGE_LATEST \
        .
    - docker push $IMAGE_TAG
    - docker push $IMAGE_LATEST
  only:
    - main
    - tags

Utiliser l’image dans FROM, docker-compose et CI

Dans un Dockerfile (FROM)

Pour construire une image qui hérite de ton image privée :

FROM registry.gitlab.com/mon-groupe/mon-app:1.0.0

# ... instructions supplémentaires
COPY config/ /app/config/

Dans un docker-compose.yml

version: "3.9"

services:
  app:
    image: registry.gitlab.com/mon-groupe/mon-app:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
    env_file:
      - .env

Sur le serveur de déploiement, tu devras te connecter à la registry avant de faire le docker compose pull :

docker login registry.gitlab.com -u [user] -p [token]
docker compose pull
docker compose up -d

Dans un autre pipeline GitLab

Si tu veux utiliser l’image d’un projet A dans le pipeline d’un projet B, tu peux utiliser un Deploy Token avec uniquement le scope read_registry :

# .gitlab-ci.yml du projet B
deploy:
  stage: deploy
  before_script:
    - docker login registry.gitlab.com -u $DEPLOY_TOKEN_USER -p $DEPLOY_TOKEN_PASS
  script:
    - docker pull registry.gitlab.com/mon-groupe/mon-app:latest
    - docker compose up -d

Gestion des tokens et des accès

C’est souvent la partie qu’on bâcle au début et qu’on regrette plus tard. Voici comment je structure les accès selon les cas d’usage :

Stocker le token de déploiement en variable CI/CD

Dans le projet qui doit puller l’image, va dans Settings > CI/CD > Variables et ajoute :

• DEPLOY_TOKEN_USER : le username du deploy token (ex: gitlab+deploy-token-123)
• DEPLOY_TOKEN_PASS : la valeur du token (marque-le Masked pour ne pas l’afficher dans les logs)

Rendre une image publique : quand et comment

Par défaut, la registry GitLab suit la visibilité du repo : privé si le repo est privé, public si le repo est public. Dans certains cas, rendre une image publique a du sens.

Rendre le repo GitLab public

La méthode la plus simple : passer le repo en public dans GitLab (Settings > General > Visibility). La registry devient automatiquement accessible en lecture sans authentification. N’importe qui peut alors faire :

docker pull registry.gitlab.com/votre-namespace/votre-repo:latest

Rendre uniquement la registry publique (repo privé)

GitLab permet aussi de garder le code source privé tout en exposant la registry publiquement. Dans Settings > Packages and registries > Container Registry, tu peux activer la visibilité publique de la registry indépendamment du repo.

Utile quand tu veux distribuer une image sans exposer le code source ni les pipelines CI/CD.

Utiliser Docker Hub pour les images vraiment publiques

Si l’image est destinée à une diffusion large (communauté open source, projet connu), Docker Hub reste la référence : meilleure indexation, pulls sans authentification sur toutes les plateformes, intégration native dans la doc officielle. Pour une image interne ou semi-publique, la registry GitLab suffit largement.

FAQ

Conclusion

La registry Docker GitLab est, selon moi, la solution la plus pragmatique pour qui utilise déjà GitLab. Pas de service tiers supplémentaire, pas de coût additionnel sur les plans usuels, et une intégration CI/CD qui élimine la gestion manuelle des credentials dans les pipelines.

Le flux que je recommande en production : Dockerfile minimal + utilisateur non-root + .gitlab-ci.yml avec cache de layers + cleanup policy activée + Deploy Tokens par environnement. C’est robuste, auditable et reproductible.

Si tu veux aller plus loin sur l’automatisation de ton infra Docker et GitLab CI, jette un oeil à mon article sur la gestion des variables et secrets GitLab CI et à comment je construis des images Docker PHP production.