Mettre à jour GitLab self-managed

GitLab publie une nouvelle version tous les mois (22 du mois). Les mises à jour mineures (ex: 18.1.0 → 18.2.0) s'appliquent en une commande apt/dnf. Les mises à jour majeures (ex: 17.x → 18.x) nécessitent de suivre un chemin d'upgrade précis, sauter des versions est une des causes les plus fréquentes de corruption de base de données.

Toujours sauvegarder avant de mettre à jour. Voir Sauvegarder et restaurer GitLab.

Comprendre le versioning GitLab

GitLab suit Semantic Versioning modifié :

18.10.1
│  │  └── Patch : correctifs de sécurité/bugs
│  └──── Minor (feature) : nouvelles fonctionnalités
└────── Major : changements majeurs, migrations DB complexes

Type	Exemple	Risque	Downtime
Patch	18.10.0 → 18.10.1	Très faible	Non (zero-downtime migrations)
Minor	18.9.x → 18.10.x	Faible	Non (en général)
Major	17.x → 18.x	Élevé si saut de versions	Possible

Glissez pour voir

Ne pas sauter de versions majeures

GitLab ne supporte pas le saut de versions majeures. Passer de 16.x directement à 18.x corrompt la base de données. Vous devez passer par toutes les versions majeures intermédiaires (16.x → 17.x → 18.x) et passer par les versions requises avant chaque major.

Utilisez l'outil officiel de chemin d'upgrade pour calculer votre chemin.

Connaître la version installée

# Version courte
sudo gitlab-rake gitlab:env:info 2>/dev/null | grep "GitLab information" -A 5

# Ou directement
cat /opt/gitlab/version-manifest.json | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(d['build_version'])"

Résultat :

18.10.1

Mise à jour mineure (même version majeure)

C'est le cas le plus courant : 18.9.5 → 18.10.1, ou 18.10.0 → 18.10.1.

1. Vérifier la version disponible

   Ubuntu/Debian

   apt-cache policy gitlab-ce

   gitlab-ce:
     Installed: 18.10.1-ce.0
     Candidate: 18.10.1-ce.0

   S'il n'y a pas de candidate plus récent, votre version est à jour.

   RHEL/Rocky

   dnf info gitlab-ce

2. Créer une sauvegarde

   sudo gitlab-backup create

   Vérifiez que la sauvegarde est complète avant de continuer.

3. Installer la mise à jour

   Ubuntu/Debian

   sudo apt-get update
   sudo apt-get install gitlab-ce

   RHEL/Rocky

   sudo dnf update gitlab-ce

   GitLab lance automatiquement gitlab-ctl reconfigure à la fin du package. La mise à jour prend 5 à 15 minutes selon les migrations de base de données.

4. Vérifier après la mise à jour

   # Version installée
   sudo gitlab-rake gitlab:env:info 2>/dev/null | head -20
   
   # Tous les services opérationnels
   sudo gitlab-ctl status
   
   # Migrations appliquées
   sudo gitlab-rake db:migrate:status 2>/dev/null | tail -10

Mise à jour majeure (changement de version majeure)

Identifier le chemin d'upgrade

Utilisez l'outil officiel : GitLab Upgrade Path Tool

Exemple : mise à jour de 16.3.x vers 18.10.x

16.3.x → 16.11.x → 17.3.x → 17.11.x → 18.10.x

Les versions intermédiaires (16.11.x, 17.3.x, 17.11.x) sont des versions requises (required stops). Vous devez vous arrêter à chaque étape et vérifier que les migrations sont complètes.

Appliquer le chemin d'upgrade

1. Mettre à jour vers la première version intermédiaire

   # Installer une version spécifique (exemple : 16.11.10)
   sudo apt-get install gitlab-ce=16.11.10-ce.0

   Pour lister les versions disponibles :

   apt-cache madison gitlab-ce | head -20

2. Attendre la fin des migrations background

   Certaines migrations s'exécutent en arrière-plan (Sidekiq) après le reconfigure. Attendez qu'elles soient toutes terminées avant de continuer :

   sudo gitlab-rake gitlab:db:validate_config

   Ou via l'interface : Admin Area → Monitoring → Background Migrations, attendez que la liste soit vide.

3. Répéter pour chaque étape du chemin

   # Étape suivante
   sudo apt-get install gitlab-ce=17.3.x-ce.0
   # ... vérifier, puis continuer

4. Installer la version cible

   sudo apt-get install gitlab-ce=18.10.1-ce.0
   # ou pour la dernière version disponible :
   sudo apt-get install gitlab-ce

Vérifier les migrations background

C'est l'étape critique souvent sautée :

# Via la console Rails
sudo gitlab-rails runner "puts Gitlab::BackgroundMigration.remaining"

Le résultat doit être 0 avant de passer à la version suivante.

Via l'interface web : Admin Area → Monitoring → Background Migrations

Mise à jour vers une version spécifique

Pour installer une version précise (utile pour les chemins d'upgrade) :

Ubuntu/Debian

# Lister les versions disponibles
apt-cache madison gitlab-ce

# Installer une version précise
sudo apt-get install gitlab-ce=18.9.5-ce.0

RHEL/Rocky

# Lister les versions disponibles
dnf list --showduplicates gitlab-ce

# Installer une version précise
sudo dnf install gitlab-ce-18.9.5-ce.0

Rollback en cas de problème

Downgrade = restauration depuis backup

GitLab ne supporte pas le downgrade direct (désinstaller et réinstaller une version antérieure). La seule méthode fiable est de restaurer depuis un backup sur la version précédente. C'est pourquoi la sauvegarde avant la mise à jour est non négociable.

Procédure de rollback :

1. Arrêter GitLab

   sudo gitlab-ctl stop

2. Réinstaller l'ancienne version

   # Remplacer par la version précédente
   sudo apt-get install gitlab-ce=18.9.5-ce.0

3. Restaurer le backup

   Suivre la procédure de restauration complète.

Automatiser les mises à jour de sécurité (patches)

Les mises à jour patch (18.10.0 → 18.10.1) sont généralement sans risque et peuvent être automatisées :

# Ubuntu/Debian : unattended-upgrades avec sélection du dépôt
sudo apt-get install -y unattended-upgrades

# Ajouter le dépôt GitLab dans la whitelist
cat >> /etc/apt/apt.conf.d/50unattended-upgrades << 'EOF'
Unattended-Upgrade::Allowed-Origins {
    "packages.gitlab.com/gitlab/gitlab-ce:noble";
};
EOF

Automatisation avec précaution

L'automatisation des patches est acceptable. Les mises à jour mineures et majeures doivent rester manuelles pour pouvoir être testées et planifiées.

Dépannage : problèmes courants

Symptôme	Cause probable	Solution
FATAL: Mixlib::ShellOut::ShellCommandFailed	Migrations DB échouées	sudo gitlab-rake db:migrate puis relancer
Service puma down après mise à jour	Incompatibilité config	sudo gitlab-ctl tail puma pour le détail
500 Whoops après reconfigure	Nouveau paramètre obligatoire	Vérifier gitlab.rb et les notes de release
Mise à jour bloquée sur "waiting for background migrations"	Migrations background en cours	Attendre ou forcer : gitlab-rails runner "..."
apt-get install gitlab-ce installe la mauvaise version	Cache apt non rafraîchi	sudo apt-get update d'abord

Glissez pour voir

À retenir

• Sauvegarder avant toute mise à jour, sans exception.
• Les mises à jour patch et mineures sont en une commande, généralement sans interruption.
• Les mises à jour majeures nécessitent un chemin d'upgrade précis, ne jamais sauter de version majeure.
• Utilisez l'outil de chemin d'upgrade pour calculer votre trajectoire.
• Attendez que les background migrations soient à zéro avant chaque étape d'un chemin d'upgrade.
• Le rollback passe obligatoirement par la restauration d'un backup.

Prochaines étapes

Sauvegarder et restaurer GitLab Stratégie de backup avant toute mise à jour.

Configuration initiale Paramètres essentiels après une installation fraîche.

GitLab Runner Configurer et gérer les runners CI/CD.

×

📖 Voir la documentation →