Mise à niveau et migration de GitLab CI/CD : guide pratique de mise en œuvre

Introduction

Les mises à niveau et les migrations de GitLab CI/CD semblent souvent risquées, car une seule erreur peut casser les pipelines de nombreux projets. Ce guide transforme ce risque en un processus contrôlé. Vous apprendrez à inventorier votre installation actuelle, à choisir le bon chemin de mise à niveau, à tester les changements en toute sécurité et à récupérer rapidement en cas de problème. L'accent est mis sur les commandes pratiques, les sorties attendues et les points de décision qui fonctionnent dans des environnements réels.

Cet article s'adresse aux ingénieurs DevOps, aux équipes de plateforme et aux responsables techniques qui gèrent des instances GitLab auto-hébergées ou prévoient une migration entre modèles de déploiement. Il couvre les mises à niveau au sein du même type d'installation, les migrations telles que le passage d'une installation source à Omnibus ou d'une infrastructure sur site vers le cloud, ainsi que les procédures de restauration en cas d'échec de mise à niveau. Les exemples utilisent des espaces réservés comme gitlab.example.com et RUNNER_TOKEN afin que vous puissiez les adapter à votre environnement sans exposer de véritables informations d'identification.

Le principe fondamental est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des vérifications en lecture seule avant et après chaque étape, et toujours disposer d'un chemin de récupération testé. N'exécutez jamais une commande que vous ne pouvez pas annuler ou vérifier.

Inventaire des versions et de l'environnement

Avant toute mise à niveau ou migration, vous devez savoir exactement ce que vous exécutez, où cela est déployé et ce qui en dépend. Cette section montre comment collecter ces informations à l'aide de la CLI et de l'API de GitLab.

Capturer la version actuelle et la topologie

Connectez-vous à votre serveur GitLab et exécutez la commande en lecture seule suivante pour obtenir la version installée :

sudo gitlab-rake gitlab:env:info

La sortie attendue comprend des lignes clés comme :

GitLab version: 15.11.0
GitLab revision: 8f2f1a2b3c4
GitLab database adapter: PostgreSQL
GitLab database version: 13.8
GitLab Shell version: 14.19.0

Si vous utilisez Omnibus, vous pouvez également exécuter sudo gitlab-ctl status pour voir l'état de tous les services. Pour les installations à partir des sources, utilisez cd /home/git/gitlab && sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production.

Ensuite, déterminez votre type de déploiement. Les plus courants sont :

Paquet Omnibus (tout-en-un)
Installation à partir du dépôt Git
Chart Helm sur Kubernetes
Conteneur Docker

Chacun a un chemin de mise à niveau documenté. Par exemple, la mise à niveau d'Omnibus nécessite des commandes apt ou yum, tandis que les mises à niveau Kubernetes nécessitent helm upgrade avec une nouvelle version du chart.

Vérifiez l'état des migrations en arrière-plan avec :

sudo gitlab-rake gitlab:background_migrations:status

Si des migrations sont encore en attente, ne poursuivez pas la mise à niveau avant qu'elles ne soient terminées.

Identifier les dépendances et les composants externes

GitLab CI/CD repose sur GitLab Runner, qui peut être installé sur des machines ou des conteneurs séparés. Listez les runners enregistrés à l'aide de la zone d'administration ou de l'API :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/runners/all"

La réponse est en JSON. Notez le champ version pour chaque runner. Les versions des runners doivent être compatibles avec la version du serveur GitLab. GitLab maintient un tableau de compatibilité : un runner avec une version majeure de retard est généralement acceptable, mais un runner avec trois versions majeures de retard peut échouer à communiquer.

Vérifiez également les intégrations externes comme le stockage d'objets (S3, GCS) pour les artefacts CI, le registre pour les images de conteneurs, et les versions de PostgreSQL/Redis. Utilisez les vérifications de santé intégrées :

sudo gitlab-rake gitlab:check

Cette commande vérifie la connectivité de la base de données, la disponibilité de Redis et les permissions du système de fichiers. Toute erreur ici doit être résolue avant une mise à niveau.

Établir une base de référence avec des vérifications en lecture seule

Avant de modifier quoi que ce soit, enregistrez l'état de fonctionnement actuel. Créez un projet de test simple et un pipeline pour confirmer que le CI/CD est fonctionnel. Par exemple, créez un .gitlab-ci.yml avec un travail trivial :

stages:
  - test

ping:
  stage: test
  script:
    - echo "Le système CI est vivant"
    - gitlab-runner --version

Exécutez le pipeline et enregistrez son journal et son statut. Cette base de référence sera comparée après la mise à niveau pour garantir l'absence de régression.

Capturez également la liste des projets actifs, des utilisateurs et des variables CI (sans leurs valeurs) à l'aide de l'API ou de la base de données. Cela aide à la restauration si nécessaire.

Chemin de configuration sûr

Une mise à niveau ou une migration sûre ne consiste pas seulement à exécuter les bonnes commandes ; il s'agit de séquencer les changements de manière à ce que chaque étape soit réversible et vérifiable. Cette section présente un chemin recommandé et les commandes spécifiques pour chaque étape.

Liste de contrôle avant mise à niveau

Sauvegardez tout. Pour Omnibus, exécutez :

sudo gitlab-backup create STRATEGY=copy

Cela crée un fichier tar dans /var/opt/gitlab/backups contenant la base de données, les dépôts, les téléversements et la configuration. Vérifiez la sauvegarde :

sudo ls -lh /var/opt/gitlab/backups/

La sortie doit montrer un fichier .tar récent avec une taille non nulle. Sauvegardez également /etc/gitlab/gitlab-secrets.json et /etc/gitlab/gitlab.rb séparément.

Passez en revue le chemin de mise à niveau. GitLab exige des mises à niveau par étapes pour les versions majeures. Vous ne pouvez pas passer directement de 14.0 à 16.5. Utilisez l'outil de mise à niveau officiel ou le chemin documenté. Par exemple, si vous êtes sur 14.0, le chemin pourrait être 14.0 -> 14.3 -> 14.6 -> 14.9 -> 15.0 -> 15.4 -> 15.8 -> 16.0 -> 16.3 -> 16.5. Chaque étape doit être terminée et validée avant la suivante.

Vérifiez les dépréciations. Consultez la liste des dépréciations pour votre version actuelle. Utilisez sudo gitlab-rake gitlab:check et recherchez les avertissements. Traitez toute dépréciation qui pourrait casser après la mise à niveau.

Effectuer la mise à niveau (exemple Omnibus)

En supposant que vous mettiez à niveau de 15.11.0 à 16.0.0 sur Ubuntu, les commandes sont :

sudo apt-get update
sudo apt-get install gitlab-ce=16.0.0-ce.0

Pour d'autres versions ou distributions, remplacez en conséquence. Après l'installation, GitLab exécute automatiquement les migrations au premier démarrage. Surveillez le processus :

sudo gitlab-ctl tail

Attendez que la sortie affiche « gitlab Reconfigured! » ou similaire. Vérifiez ensuite le statut :

sudo gitlab-ctl status

Tous les services doivent être run: ... (pid ...) sans état d'arrêt.

Exécutez les vérifications post-installation :

sudo gitlab-rake gitlab:check

Recherchez toute nouvelle erreur. Si tout est clair, passez à la version suivante dans le chemin de mise à niveau.

Gérer les migrations (Omnibus vers Kubernetes, etc.)

Les migrations entre types de déploiement sont plus complexes. Par exemple, passer d'Omnibus à un chart Helm implique :

Exporter les données d'Omnibus à l'aide de la sauvegarde et les importer dans une instance PostgreSQL gérée par le chart.
Transférer les dépôts et les téléversements vers le stockage d'objets.
Mettre à jour le DNS et l'équilibreur de charge.
Reconfigurer les runners pour pointer vers la nouvelle instance.

Un script de migration détaillé dépasse le cadre de ce guide, mais le principe est le même : chaque étape de déplacement de données doit être vérifiée avec des sommes de contrôle et des restaurations de test avant le basculement.

Vérification et diagnostic

Après chaque mise à niveau ou migration, vous devez vérifier que le système fonctionne comme prévu. Cette section fournit des vérifications spécifiques et des commandes de diagnostic.

Vérifications de santé de base

Exécutez les commandes suivantes dans l'ordre :

sudo gitlab-ctl status
sudo gitlab-rake gitlab:check
curl -I https://gitlab.example.com

La première doit montrer tous les services en cours d'exécution. La deuxième doit se terminer par « Checking GitLab ... Finished » sans erreur. La troisième doit renvoyer un code HTTP 200 ou 302 (redirection vers la connexion).

Vérifiez à nouveau les migrations en arrière-plan :

sudo gitlab-rake gitlab:background_migrations:status

Ne doit montrer aucune migration en attente. Si certaines sont bloquées, consultez la section sur les échecs ci-dessous.

Vérification fonctionnelle du CI/CD

Créez un nouveau projet ou utilisez un projet de test. Poussez un .gitlab-ci.yml simple :

stages:
  - verify

upgrade-check:
  stage: verify
  script:
    - echo "Le pipeline après mise à niveau fonctionne"
    - gitlab-runner --version
    - git --version

Exécutez le pipeline et assurez-vous qu'il réussit. Vérifiez ensuite l'enregistrement des runners :

sudo gitlab-runner list

La sortie doit montrer tous les runners et leurs exécuteurs. Si un runner est manquant ou affiche une erreur, résolvez le problème avant de continuer.

Utilisez l'API pour vérifier la cohérence des versions :

curl --header "PRIVATE-TOKEN: <jeton>" "https://gitlab.example.com/api/v4/version"

Réponse :

{"version": "16.0.0", "revision": "abcdefg"}

Comparez cela à la version installée.

Journaux et métriques

Vérifiez les journaux pour les erreurs :

sudo gitlab-ctl tail gitlab-rails
sudo gitlab-ctl tail postgresql

Recherchez les exceptions, les migrations échouées ou les erreurs de connexion. Surveillez également les métriques système comme le CPU, la mémoire et l'utilisation du disque pendant les premières exécutions de pipeline après la mise à niveau. Utilisez htop, df -h et free -m.

Si vous utilisez Prometheus, vérifiez le point de terminaison des métriques intégrées :

curl https://gitlab.example.com/-/metrics

Cela doit renvoyer une grande charge utile de texte de métriques. Tout échec indique un problème avec l'intégration de la surveillance.

Modes de défaillance et récupération

Même avec une planification minutieuse, les mises à niveau peuvent échouer. Cette section décrit les modes de défaillance courants, comment les diagnostiquer et les étapes de récupération.

Échecs de mise à niveau courants et correctifs

Migrations en arrière-plan bloquées. Parfois, les migrations ne se terminent pas automatiquement, souvent en raison de données à long terme ou de verrous. Diagnostiquez avec :

sudo gitlab-rake gitlab:background_migrations:status

Si bloquées, vérifiez les journaux :

sudo gitlab-ctl tail sidekiq

Recherchez les interblocages ou les délais d'attente. Souvent, redémarrer Sidekiq aide :

sudo gitlab-ctl restart sidekiq

Si toujours bloquées, consultez le support GitLab ou exécutez la migration manuellement avec prudence.

Échec de migration de base de données. Si gitlab:check signale une migration échouée, récupérez l'ID de migration à partir de l'erreur et vérifiez son statut dans la table schema_migrations. Vous pouvez tenter de la réexécuter, mais assurez-vous d'abord qu'il n'y a pas de changements partiels. Annuler une migration n'est pas officiellement pris en charge, donc restaurer à partir de la sauvegarde peut être plus sûr.

Incompatibilité des runners. Après la mise à niveau, les runners peuvent ne pas récupérer les travaux. Vérifiez les journaux des runners :

sudo gitlab-runner --debug run

Recherchez « 401 Unauthorized » ou « version mismatch ». Mettez à jour le runner vers une version compatible :

sudo apt-get update && sudo apt-get install gitlab-runner=16.0.0

Remplacez par une version appropriée du tableau de compatibilité.

Erreurs de fichier de configuration. Les erreurs Omnibus proviennent souvent d'un mauvais gitlab.rb. Exécutez :

sudo gitlab-ctl reconfigure

Si la reconfiguration échoue, examinez /var/log/gitlab/reconfigure/current et corrigez le paramètre de configuration.

Procédure de restauration

Si une mise à niveau cause de graves problèmes et que vous devez revenir en arrière, suivez ces étapes :

Arrêtez les services GitLab :

sudo gitlab-ctl stop

Restaurez la sauvegarde d'avant la mise à niveau :

sudo gitlab-backup restore BACKUP=<horodatage_de_la_sauvegarde>

Par exemple, si votre fichier de sauvegarde est 1699999999_2023_11_14_15.11.0_gitlab_backup.tar, utilisez BACKUP=1699999999_2023_11_14_15.11.0.

Restaurez les secrets et la configuration :

sudo cp /chemin/vers/sauvegarde/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json
sudo cp /chemin/vers/sauvegarde/gitlab.rb /etc/gitlab/gitlab.rb

Reconfigurez et redémarrez :

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

Vérifiez avec les contrôles de santé et le pipeline de base.

Remarque : Une restauration n'est possible que si vous disposez d'une sauvegarde complète prise immédiatement avant la mise à niveau. Testez toujours votre processus de restauration de sauvegarde dans un environnement de préproduction pour vous assurer qu'il fonctionne.

Liste de contrôle des opérations

Cette liste de contrôle consolide les étapes clés en un manuel reproductible. Attribuez un responsable à chaque élément et révisez la liste de contrôle tous les trimestres.

Étape	Action	Commande / Vérification	Résultat attendu	Responsable	Fréquence de révision
1	Inventorier la version et la topologie actuelles	`sudo gitlab-rake gitlab:env:info`	La version correspond au point de départ prévu	Priya Shah, responsable ingénierie	Trimestrielle
2	Vérifier que les migrations en arrière-plan sont terminées	`sudo gitlab-rake gitlab:background_migrations:status`	Aucune migration en attente	Marcus Chen, ingénieur DevOps	Avant chaque mise à niveau
3	Créer une sauvegarde complète avec la stratégie de copie	`sudo gitlab-backup create STRATEGY=copy`	Le fichier de sauvegarde existe dans /var/opt/gitlab/backups	Priya Shah	Avant chaque mise à niveau
4	Vérifier la compatibilité des runners	Appel API pour lister les runners	Tous les runners sont dans la plage de versions prise en charge	Marcus Chen	Avant chaque mise à niveau
5	Effectuer la mise à niveau par étapes en suivant le chemin	`sudo apt-get install gitlab-ce=<version>`	Les services redémarrent sans erreur	Marcus Chen	À chaque étape de mise à niveau
6	Exécuter les vérifications de santé après mise à niveau	`sudo gitlab-rake gitlab:check`	Aucune erreur signalée	Marcus Chen	Après chaque étape
7	Exécuter un test de pipeline fonctionnel	Pousser un projet de test et exécuter le pipeline	Le pipeline réussit	Priya Shah	Après chaque étape
8	Vérifier la procédure de restauration en préproduction	Simuler la restauration hors production	La restauration se termine et le système fonctionne	Priya Shah	Trimestrielle
9	Mettre à jour la documentation et le manuel	Modifier le wiki interne	Le manuel reflète la version et les étapes actuelles	Marcus Chen	Après chaque mise à niveau

Pièges courants et comment les éviter

De nombreux échecs de mise à niveau sont causés par des erreurs évitables. Voici les pièges les plus courants, pourquoi ils surviennent et comment s'en remettre.

Piège 1 : Ignorer la sauvegarde ou ne pas tester la restauration

Pourquoi cela arrive : Les équipes supposent que la mise à niveau réussira et ne veulent pas consacrer de temps aux sauvegardes.

Conséquence : Si la mise à niveau corrompt les données, il n'y a aucun moyen de récupérer.

Comment éviter : Exécutez toujours une sauvegarde complète avec gitlab-backup create et copiez également les secrets. Testez le processus de restauration dans un environnement de préproduction au moins une fois. Documentez les étapes de restauration.

Récupération : Si vous n'avez pas de sauvegarde, vous devrez peut-être vous appuyer sur des instantanés de base de données ou de système de fichiers s'ils sont disponibles. Sinon, la perte de données est probable.

Piège 2 : Sauter plusieurs versions majeures

Pourquoi cela arrive : Les développeurs veulent passer rapidement à la dernière version ou supposent une compatibilité ascendante.

Conséquence : La mise à niveau peut échouer avec des erreurs de migration ou laisser la base de données dans un état incohérent.

Comment éviter : Suivez le chemin de mise à niveau officiel. Mettez à niveau une version majeure à la fois, en exécutant des vérifications entre chaque.

Récupération : Si vous avez sauté des versions, vous pourrez peut-être restaurer à partir de la sauvegarde et suivre le bon chemin. Sinon, consultez le support.

Piège 3 : Ignorer la compatibilité des runners

Pourquoi cela arrive : Les équipes se concentrent sur le serveur et oublient les runners, qui peuvent être sur des machines séparées.

Conséquence : Après la mise à niveau du serveur, les runners ne parviennent pas à enregistrer les travaux ou les exécutent avec des erreurs.

Comment éviter : Vérifiez les versions des runners avant la mise à niveau et mettez à jour les runners si nécessaire. Maintenez une matrice de compatibilité.

Récupération : Mettez à jour les runners vers une version compatible. Si le runner ne peut pas être mis à jour immédiatement, épinglez le serveur à une version qui prend en charge l'ancien runner jusqu'à ce que vous puissiez mettre à jour les deux.

Piège 4 : Ne pas surveiller les migrations en arrière-plan

Pourquoi cela arrive : Les migrations en arrière-plan s'exécutent de manière asynchrone, et les équipes supposent qu'elles sont terminées.

Conséquence : Certaines fonctionnalités peuvent ne pas fonctionner correctement parce que le schéma de la base de données ou les données ne sont pas entièrement migrés.

Comment éviter : Vérifiez toujours l'état des migrations après la mise à niveau et ne continuez pas tant qu'il n'est pas clair.

Récupération : Si les migrations sont bloquées, identifiez le travail et résolvez les problèmes tels que les verrous ou les délais d'attente. Redémarrez Sidekiq si nécessaire. Dans le pire des cas, restaurez à une version précédente et réexécutez avec plus de ressources.

Piège 5 : Modifier la configuration sans contrôle de version

Pourquoi cela arrive : Les ingénieurs modifient directement /etc/gitlab/gitlab.rb ou d'autres fichiers de configuration sans suivre les changements.

Conséquence : Un mauvais changement de configuration peut casser l'instance, et il est difficile de revenir en arrière.

Comment éviter : Conservez les fichiers de configuration dans un contrôle de version et utilisez un outil de gestion de configuration. Testez toujours les changements en préproduction.

Récupération : Restaurez la configuration précédente à partir du contrôle de version ou de la sauvegarde et reconfigurez.

Conclusion

Les mises à niveau et les migrations de GitLab CI/CD ne doivent pas être effrayantes. En suivant un processus structuré — inventaire, sauvegarde, mise à niveau par étapes, vérification et restauration documentée — vous pouvez minimiser les temps d'arrêt et éviter la perte de données. Ce guide a fourni des commandes concrètes et des listes de contrôle que vous pouvez adapter à votre environnement.

La prochaine étape consiste à appliquer cela à votre propre système. Commencez par une vérification à faible risque : vérifiez votre version actuelle, assurez-vous que toutes les migrations en arrière-plan sont terminées et créez une sauvegarde de test. Planifiez ensuite votre chemin de mise à niveau avec l'outil officiel. N'oubliez pas que chaque environnement est unique, alors testez d'abord en préproduction et ayez toujours un plan de restauration.

Un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. Avec ces pratiques, vous pouvez garder votre plateforme GitLab CI/CD sécurisée, performante et à jour.