Installer GitLab CE sur VPS : guide complet

GitHub et Bitbucket sont des services gérés : pratiques au démarrage, mais leur modèle tarifaire évolue avec la taille de l'équipe, les minutes CI sont comptées sur les offres gratuites, et votre code est hébergé sur une infrastructure tierce. GitLab CE renverse cette équation : vous déployez la forge sur votre VPS, vous gardez la maîtrise totale du code et des données, et la CI/CD est incluse sans quota de minutes imposé par un tiers — seule la capacité de votre machine limite le nombre de jobs parallèles. Pour une agence ou une équipe de développeurs qui facture au client ou traite des données sensibles, ce contrôle est souvent non négociable. GitLab CE est aujourd'hui l'une des forges git les plus déployées en self-hosted : sa base de code est publique, son noyau est libre, et ses dix ans d'existence lui ont valu une communauté de contributeurs qui maintient l'outil actif entre deux releases Enterprise.

GitLab CE est gourmand en mémoire — c'est l'un de ses inconvénients les plus cités par rapport à Forgejo ou Gitea. Prévoyez 4 Go de RAM minimum pour un usage léger (moins de dix utilisateurs actifs) ; 8 Go sont recommandés dès que vous ajoutez des runners sur la même machine ou que vous activez le registry Docker. En dessous de 4 Go, Puma et Sidekiq se disputent la mémoire et GitLab répond en 502 sous charge. Côté disque, comptez au moins 20 Go pour l'installation et les dépôts initiaux — prévoir 50 Go si vous comptez stocker des images Docker dans le registry. Vous avez également besoin : d'un nom de domaine pointant vers l'IP du VPS (par exemple git.votredomaine.com) pour que Let's Encrypt puisse émettre le certificat TLS ; des ports 80, 443 et 22 ouverts dans votre pare-feu (le port 22 est utilisé par GitLab pour les push SSH — si votre daemon SSH système écoute aussi sur 22, vous devrez le déplacer sur un autre port) ; de Docker Engine et du plugin Compose v2 installés (docker compose version doit répondre v2.x).

L'executor Docker est le choix recommandé pour la plupart des projets : chaque job s'exécute dans un conteneur isolé, sans polluer l'environnement du runner. Après l'enregistrement du runner (étape 8 ci-dessus), son fichier de configuration /etc/gitlab-runner/config.toml contient un bloc [runners.docker]. Ajoutez-y volumes = ["/cache"] pour conserver le cache entre les builds, et pull_policy = ["if-not-present"] pour ne pas retirer l'image à chaque job si elle est déjà présente localement — cela réduit sensiblement la durée des premiers stages.

Un pipeline de base pour un projet Node.js ou PHP tient en une vingtaine de lignes dans .gitlab-ci.yml à la racine du dépôt :

stages:
  - test
  - build
  - deploy

variables:
  DOCKER_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

test:unit:
  stage: test
  image: node:20-alpine
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - node_modules/
  script:
    - npm ci
    - npm test
  only:
    - merge_requests
    - main

build:image:
  stage: build
  image: docker:26
  services:
    - docker:26-dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $DOCKER_IMAGE .
    - docker push $DOCKER_IMAGE
  only:
    - main

deploy:prod:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | ssh-add -
  script:
    - ssh -o StrictHostKeyChecking=no [email protected] "docker pull $DOCKER_IMAGE && docker compose up -d"
  only:
    - main
  when: manual

Les variables CI_REGISTRY_USER, CI_REGISTRY_PASSWORD et CI_REGISTRY sont injectées automatiquement par GitLab CE pour le registry intégré — aucune configuration manuelle. La variable SSH_PRIVATE_KEY est à définir dans Settings → CI/CD → Variables du projet, marquée Masked pour qu'elle n'apparaisse pas dans les logs. Le job deploy:prod est positionné en when: manual : il ne se déclenche pas automatiquement mais attend un clic dans l'interface ou via l'API — un garde de sécurité minimal avant d'écrire en production.

Pour vérifier que le runner a bien décroché le job, rendez-vous dans CI/CD → Jobs : chaque job affiche son runner assigné, sa durée et son code de sortie. Un job bloqué sur « pending » indique que le runner n'a pas de slot disponible (vérifier concurrent dans /etc/gitlab-runner/config.toml, défaut à 1) ou qu'il est offline.

GitLab envoie des emails à chaque merge request, mention, pipeline terminé ou alerte de sécurité. Une configuration SMTP absente ou erronée coupe silencieusement ces notifications — les utilisateurs ne le remarquent qu'après un incident.

Le bloc complet à placer dans GITLAB_OMNIBUS_CONFIG pour un relais SMTP authentifié (exemple avec un serveur compatible STARTTLS sur le port 587) :

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'smtp.votredomaine.com'
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = '[email protected]'
gitlab_rails['smtp_password'] = ENV['GITLAB_SMTP_PASSWORD']
gitlab_rails['smtp_authentication'] = 'login'
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = '[email protected]'
gitlab_rails['gitlab_email_reply_to'] = '[email protected]'

Si votre relais exige TLS direct (port 465), remplacez smtp_enable_starttls_auto = true par smtp_tls = true et ajustez le port. Pour les relais qui n'exigent pas d'authentification (serveur interne, Postfix local), posez smtp_authentication = false et supprimez smtp_user_name et smtp_password.

Principaux pièges :
- Clé hors du bloc omnibus. Une clé GITLAB_SMTP_ADDRESS définie comme variable d'environnement Docker n'est pas lue par Omnibus — elle est ignorée sans avertissement. Toute configuration Rails passe par le bloc Ruby dans GITLAB_OMNIBUS_CONFIG.
- Indentation YAML dans docker-compose.yml. Si GITLAB_OMNIBUS_CONFIG est un bloc multilignes YAML, chaque retour à la ligne doit être explicitement représenté (\n ou bloc |). Une erreur d'indentation peut couper le bloc au milieu et laisser GitLab sans SMTP sans générer d'erreur au démarrage.
- Test depuis la console Rails. Après chaque modification, relancez le conteneur (docker compose restart gitlab) et testez immédiatement : docker exec -it gitlab-gitlab-1 gitlab-rails console -e production puis Notify.test_email('[email protected]', 'Test', 'OK').deliver_now. Lisez la réponse — une exception SMTP apparaît dans la console avant même que l'email parte.

GitLab CE embarque une commande de sauvegarde complète qui archive en un seul fichier tar les dépôts git, la base de données PostgreSQL, les uploads, les artefacts CI et les clés de configuration. La commande de référence :

docker exec -t gitlab-gitlab-1 gitlab-backup create

L'archive est créée dans /var/opt/gitlab/backups/ à l'intérieur du conteneur, soit /opt/gitlab/data/backups/ sur l'hôte si vous avez monté le volume comme indiqué. Elle porte un nom de la forme <timestamp>_<version>_gitlab_backup.tar.

Attention : la sauvegarde gitlab-backup create n'inclut pas deux fichiers critiques — /etc/gitlab/gitlab.rb (la configuration Omnibus) et /etc/gitlab/gitlab-secrets.json (les clés de chiffrement). Sans ces fichiers, une restauration échoue ou déchiffre mal les tokens. Sauvegardez-les séparément :

tar czf /opt/gitlab/config-secrets-$(date +%Y%m%d).tar.gz \
  /opt/gitlab/config/gitlab.rb \
  /opt/gitlab/config/gitlab-secrets.json

Restaurer une instance depuis une sauvegarde nécessite trois étapes dans l'ordre :

1. Installez une instance GitLab CE de la même version mineure que celle qui a produit la sauvegarde. La restauration entre versions différentes n'est pas supportée.
2. Copiez l'archive tar dans /opt/gitlab/data/backups/ et restaurez gitlab.rb et gitlab-secrets.json dans /opt/gitlab/config/.
3. Arrêtez les services qui écrivent en base, puis lancez la restauration :

docker exec -it gitlab-gitlab-1 gitlab-ctl stop puma
docker exec -it gitlab-gitlab-1 gitlab-ctl stop sidekiq
docker exec -it gitlab-gitlab-1 gitlab-backup restore BACKUP=<timestamp>_<version>
docker exec -it gitlab-gitlab-1 gitlab-ctl restart
docker exec -it gitlab-gitlab-1 gitlab-rake gitlab:check SANITIZE=true

La commande gitlab:check à la fin vérifie l'intégrité de l'installation et signale les dépôts corrompus ou les permissions incorrectes. Planifiez la sauvegarde complète à 3 h du matin et synchronisez vers un stockage externe (S3 via rclone, bucket OVH, NAS distant) : une sauvegarde locale qui brûle avec le VPS n'est pas une sauvegarde.

502 Bad Gateway au démarrage. GitLab met environ 5 minutes à être pleinement opérationnel. Si le 502 persiste, vérifiez que Puma a démarré : docker exec gitlab-gitlab-1 gitlab-ctl status puma. Un manque de RAM est la cause la plus fréquente — assurez-vous d'avoir au moins 4 Go disponibles. SMTP ne fonctionne pas. La première chose à vérifier : le bloc gitlab_rails['smtp_*'] est-il bien à l'intérieur de GITLAB_OMNIBUS_CONFIG, et non défini comme variable d'environnement séparée ? Une indentation incorrecte dans le YAML ou une clé hors du bloc omnibus est silencieuse — GitLab démarre normalement mais ignore la configuration SMTP. Testez depuis la console Rails (étape 9). Runner non connecté. Si le runner s'affiche en gris ou « offline », vérifiez qu'il peut joindre votre instance : gitlab-runner verify --url https://git.votredomaine.com. Un certificat TLS auto-signé ou un DNS non résolvable depuis la machine du runner sont les causes habituelles. Vérifiez également que le token utilisé à l'enregistrement est celui du bon niveau (instance, groupe ou projet).

Sidekiq queue stuck — jobs bloqués indéfiniment. Sidekiq traite les jobs asynchrones de GitLab (emails, imports, webhooks, indexation). Si des jobs s'accumulent sans être consommés, vérifiez d'abord l'état du worker :

docker exec gitlab-gitlab-1 gitlab-ctl status sidekiq
docker exec gitlab-gitlab-1 gitlab-rake gitlab:sidekiq:check

Une queue bloquée tient souvent à un job qui a levé une exception non rattrapée et s'est mis en « retry » infini. Pour vider une queue spécifique sans redémarrer GitLab : docker exec -it gitlab-gitlab-1 gitlab-rails console -e production puis Sidekiq::Queue.new('mailers').clear. Si Sidekiq consomme plus de 1 Go de RAM, docker exec gitlab-gitlab-1 gitlab-ctl restart sidekiq le ré-initialise sans affecter les jobs en attente (ils restent dans Redis).

Puma / Unicorn timeout — 503 intermittents sous charge. Les timeouts Puma (appels lents à la base, requêtes Rails mal optimisées) se lisent dans /var/log/gitlab/puma/puma_stderr.log. La première action est d'augmenter le timeout si le VPS est lent mais fonctionnel : dans GITLAB_OMNIBUS_CONFIG, ajoutez puma['worker_timeout'] = 90 (défaut 60 s). Si les timeouts persistent, la cause est presque toujours un manque de RAM ou un nombre de workers inadapté — voir la section optimisation RAM ci-dessous.

OOM sur Gitaly — dépôts inaccessibles après un kill. Gitaly est le service qui répond aux opérations git (clone, fetch, push). Si le noyau le tue par OOM (vérifiable dans dmesg | grep -i kill), tous les accès git tombent en erreur jusqu'au redémarrage du service. Gitaly consomme environ 200 à 400 Mo sur une installation légère ; avec des dépôts volumineux ou des opérations de repack simultanées, il peut dépasser 1 Go. Surveillez sa consommation avec docker exec gitlab-gitlab-1 gitlab-ctl status gitaly et, si le VPS est juste en RAM, envisagez de limiter les tâches de maintenance automatique dans GITLAB_OMNIBUS_CONFIG : gitaly['configuration']['git']['catfile_cache_size'] = 5 (défaut 100) réduit les objets git gardés en cache. En cas d'OOM répété, la solution durable est d'augmenter la RAM ou d'ajouter du swap (voir ci-dessous).

Container exited au démarrage. Si le conteneur sort immédiatement après docker compose up, consultez les logs avant la sortie : docker compose logs gitlab | tail -50. Les causes les plus fréquentes sont un conflit de port 22 (daemon SSH système actif), un volume non accessible en écriture (chown -R 998:998 /opt/gitlab/data) ou un GITLAB_OMNIBUS_CONFIG avec une syntaxe Ruby invalide (une virgule manquante, un guillemet non fermé).

GitLab CE en configuration par défaut alloue plusieurs workers Puma et autant de threads Sidekiq qu'il détecte de cœurs CPU. Sur un VPS de 4 Go avec 2 vCPU, cela peut dépasser la mémoire disponible dès qu'un pipeline lourd tourne en parallèle. Deux leviers immédiats.

Réduire les workers Puma. Dans GITLAB_OMNIBUS_CONFIG :

puma['worker_processes'] = 2
puma['min_threads'] = 1
puma['max_threads'] = 4

Chaque worker Puma consomme environ 200 à 300 Mo. Deux workers suffisent pour moins de quinze utilisateurs actifs simultanés. Un seul worker (worker_processes = 0) est possible mais retire la tolérance aux pannes de worker.

Ajouter du swap. GitLab recommande d'avoir au minimum autant de swap que de RAM. Sur un VPS sans swap préconfiguré :

fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Le swap ne remplace pas la RAM — il évite le crash OOM quand un pic de charge momentané déborde — mais il ralentit GitLab si le système doit y recourir en permanence. Si free -h montre une utilisation swap régulière au repos, c'est le signe que le VPS est sous-dimensionné.

Recommandations RAM et CPU par taille d'équipe

| Taille d'équipe | RAM recommandée | vCPU | Notes |
|---|---|---|---|
| 1–5 développeurs | 4 Go | 2 | Runners sur la même machine possibles avec swap |
| 5–15 développeurs | 8 Go | 4 | Runner dédié conseillé dès 8+ pipelines/jour |
| 15–30 développeurs | 16 Go | 8 | Registry Docker actif, Gitaly sous charge |
| 30+ développeurs | 32 Go+ | 16+ | Séparer Gitaly et Sidekiq sur des machines dédiées |

Ces valeurs correspondent à un GitLab CE avec registry Docker actif et pipelines CI réguliers. Sans CI (runners absents), divisez par deux les valeurs de RAM. Avec un registry très sollicité (images > 2 Go fréquentes), comptez 50 Go de disque supplémentaire et surveillez df -h /opt/gitlab/data — un disque plein stoppe GitLab sans avertissement préalable.

GitLab CE est le bon choix si votre équipe a besoin d'une CI/CD robuste directement intégrée à la forge, d'un registry Docker privé sur votre domaine, de pipelines de déploiement avec environments et deploy tokens, ou d'une gestion de projet avec issues, milestones et kanban sans outil tiers. Son empreinte mémoire (4–8 Go) est le prix de cette richesse fonctionnelle. Forgejo ou Gitea s'imposent quand la mémoire est la contrainte principale, quand la forge est l'unique besoin (pas de CI intégrée) et que vous pilotez la CI avec un outil externe (Woodpecker, Drone, GitHub Actions via un runner). Sur un VPS de 2 Go, GitLab CE n'est pas viable ; Forgejo tourne sur 256 Mo. Sur un VPS de 8 Go dédié à une équipe de développeurs, GitLab CE offre un environnement complet que GitHub met sur sa plateforme SaaS — sous votre contrôle et sans abonnement mensuel par utilisateur.