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 expose à des migrations en échec et à une base de données inutilisable.

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

Cette page porte sur l'instance GitLab elle-même : le GitLab Runner est un paquet distinct, présenté dans Maîtriser GitLab Runner.

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 fait échouer les migrations et peut laisser la base de données inutilisable. 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)

Une version majeure ne se saute jamais d'un coup : GitLab impose des versions requises intermédiaires, parce que chacune porte des migrations de base de données que la suivante suppose terminées. La procédure tient en trois gestes : calculer le chemin, l'appliquer palier par palier, et attendre la fin des migrations en arrière-plan avant de passer au palier suivant.

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-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

   Zéro ligne retournée signifie que toutes les migrations par lots sont terminées. À partir de GitLab 18.9, sudo gitlab-rake gitlab:background_migrations:list les liste pour toutes les bases (gitlab:background_migrations:status avant 18.9).

   Ou via l'interface : Admin → Monitoring → Background migrations, onglets Queued et Finalizing : attendez qu'ils soient vides.

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 la plus souvent sautée : passer au palier suivant alors que des migrations par lots tournent encore. La vérification est celle de l'étape 2 ci-dessus : la requête sur batched_background_migrations doit rendre zéro ligne, ou gitlab:background_migrations:list (à partir de 18.9) ne plus rien lister, et les onglets Queued et Finalizing de l'interface doivent être vides.

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

La plupart des échecs de mise à jour se lisent dans les journaux du service fautif (sudo gitlab-ctl tail <service>) et viennent soit d'une migration de base interrompue, soit d'un paramètre de gitlab.rb devenu obligatoire. Le tableau relie chaque symptôme à sa cause la plus probable.

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 (voir Configuration initiale) et les notes de release
Mise à jour bloquée sur "waiting for background migrations"	Migrations background en cours	Attendre la fin des migrations (voir « Vérifier les migrations background »)
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.

×

📖 Voir la documentation →