Installation, configuration, upgrade de Gitlab

Introduction

Dans cette seconde partie, je vais détailler les différentes tâches d’administration sur Gitlab, et plus précisément les parties sauvegardes, restaurations, migrations et mises à jour.

Nous allons commencer cependant par la configuration HTTPS, non abordée lors de l’article précédent.

HTTPS

Lors du billet précédent, les exemples donnés passaient par HTTP mais ce n’est pas pérenne. Pour apporter plus de sécurité, il faut forcer le passage par HTTPS pour les connexions.

Gitlab

Pour la partie Gitlab, il suffit d’ajouter 2 grands éléments à la configuration. Il faut d’abord un certificat approprié et ensuite un léger changement de configuration.

Certificat

Concernant le certificat, il dépendra de la structure relative à l’hébergement. Si le Gitlab est auto-hébergé mais accessible depuis Internet, alors on s’appuiera sur un fournisseur type Let’s Encrypt.

Dans le cas où l’équipe héberge le Gitlab mais qu’il reste isolé dans un sous-réseau, il faudra alors probablement géré les certificats (voir la Root CA) au niveau de l’équipe.

Pour réaliser un cas un peu complexe, j’ai créée une Root CA puis l’ai utilisé pour générer un certificat. Gitlab a besoin de 2 fichiers pour gérer le HTTPS :

la clé privée associé au certificat
la chaîne de certification, contenant le certificat serveur, le certificat Root CA (et éventuellement les certificats intermédiaires)

Ces deux fichiers doivent également être nommé de manière spécifique. Tous deux doivent être égaux au hostname du Gitlab plus l’extension associé.

Par exemple, j’ai mon hostname Gitlab = “newgitlab.watylocal”, mes fichiers doivent être :

newgitlab.watylocal.key pour la clé
newgitlab.watylocal.crt pour la chaîne de certificats

Gitlab s’attend à ce que ces fichiers soit présents sous /etc/gitlab/ssl par défaut. Dans le cas de notre installation Docker, cela correspond à /srv/gitlab/config/ssl.

Configuration

Concernant la configuration, tout passe par le docker-compose.yml.

Avant

      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://newgitlab.watylocal'

Ce qui change :

Changement sur external_url : on passe en https
On désactive la gestion certificat par Lets Encrypt (défaut)
On force NGINX à rediriger HTTP -> https

Après

      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://newgitlab.watylocal'
        letsencrypt['enable'] = false
        nginx['redirect_http_to_https'] = true

Ces éléments sont tous détaillés dans la documentation.

Gitlab-Runner

Dans le cas d’une mise en place de certificat avec notre propre PKI, il faut que le runner possède le certificat Root CA afin de pouvoir vérifier le certificat du Gitlab lors de la mise en relation.

Par défaut, le runner Gitlab lit dans le certificat store pour avoir les différents Root/Intermediate CA pour pouvoir authentifier les certificats. Or, dans notre cas, c’est un container qui aurait ce store, et pas l’hôte. On pourrait éventuellement passer le store machine en mode read-only.

Cependant, il existe une option de gitlab-runner register qui permet de spécifier quel fichier utiliser pour vérifier les certificats, c’est --tls-ca-file.

J’ajoute le certificat dans le bon répertoire (volume partagé), dans mon cas /srv/gitlab-runner/config/ (correspondant à /etc/gitlab-runner/ dans le container).

La commande pour enregistrer son runner devient alors :

docker exec -it gitlab-runner-main \
    gitlab-runner register \
    --url https://$HOSTNAME \
    --token "glrt-XYZ" \
    --tls-ca-file=/etc/gitlab-runner/ca-certificate.crt \
    --non-interactive \
    --executor "docker" \
    --docker-image alpine:latest \
    --description "docker-runner"

Backup et Restore

Sauvegarde

Pour réaliser une sauvegarde d’une installation Docker, il est suffisant de sauvegarder les volumes montés par le conteneur.

Pour un cron classique la ligne : * 1 * * * dt=$(date +"\%F-\%H\%M\%S") && tar czf /srv/backups/gitlab-docker-${dt}.tar.gz /srv/gitlab 2> /srv/backups/error-${dt}.log && echo "Backup done : $dt" >> /srv/backups/gitlab-docker-backups.txt

Sinon, pour un fichier sous /etc/cron.daily/

#!/bin/bash
set -e
dt=$(date +"%F-%H%M%S")
tar czf /srv/backups/gitlab-docker-${dt}.tar.gz /srv/gitlab 2> /srv/backups/error-${dt}.log
echo "Backup done : $dt" >> /srv/backups/gitlab-docker-backups.txt

(Des exemples plus détaillés sont dispos dans le repo, notamment pour l’encryption)

Ensuite, il n’y a plus qu’à pousser la sauvegarde en lieu sûr.

Restauration

Pour la restauration, il suffit de faire le chemin en sens inverse et de remettre le contenu de l’archive dans les bons répertoires.

# déchiffrer eventuellement
sudo gpg --decrypt ./gitlab-docker-2025-10-30-133001.tar.gz.gpg > ./gitlab-docker-2025-10-30-133001.tar.gz
# restauration à proprement parler
sudo tar xzf ./gitlab-docker-2025-10-30-133001.tar.gz -C /srv/

Sauvegardes et restauration sont à faire lors de faible activité et/ou avec le serveur coupé de préférence.

Migration

La migration d’une instance Gitlab est relativement aisé d’un point de vue technique serveur. D’autres éléments peuvent augmenter la difficulté.

D’un point de vue strictement du serveur, la migration n’est simplement qu’une restauration de la sauvegarde mais sur une autre machine.

Il faut cependant s’assurer que la migration se fait bien sur la même version de Gitlab que la sauvegarde. C’est pourquoi il sera judicieux d’inclure le fichier docker-compose.yml dans la sauvegarde.

La difficulté de cette migration est également la gestion réseau et accès. S’il faut garder la même adresse de Gitlab interne, alors il faut bien gérer la partie DNS. Dans le cas contraire, il faudra que tous les développeurs changent l’adresse du dépôt distant dans leur configuration Git.

Upgrade

Le processus d’upgrade de Gitlab est assez simple et bien documenté.

Il suffit d’appliquer la nouvelle version de Gitlab sur l’ancienne afin d’upgrader. Le démarrage du nouveau Gitlab va lancer les migrations BDD en arrière-plan afin de se conformer à la nouvelle version.

Attention toutefois, toutes les migrations ne sont pas incluses dans la dernière version en date. Pour migrer correctement, il faut suivre un certain chemin de versions successives. C’est l’ “upgrade path” de Gitlab. Globalement, cela consiste à installer toutes les 2 ou 3 versions mineures.

Gitlab a un outil permettant de construire son chemin d’upgrade. Il s’agit d’un site disponible pour le support de Gitlab : https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/ .

Selon la version de départ et le mode d’installation, on se retrouve avec des instructions concernant les différentes versions à installer progressivement.

En partant de la 16.10.10 et avec un contenu de démo j’ai mis un peu moins de 3 heures à réaliser la migration.

La partie la plus longue est bien sûr celle contenant les jobs de migrations en arrière-plan. Le temps d’exécution des jobs variera selon la taille des données dans la base évidemment.

Ce travail d’upgrade sur une démo correspond à une préparation, un “tour à blanc” afin de préparer une migration de prod plus sereinement.

J’ai également profité de ces étapes pour construire de petits utilitaires afin de simplifier les lancements et le suivi des migrations. Les outils sont dans le repo Gitlab.

J’utilise :

launch.sh : sur-couche autour de docker compose up et docker ps. Permet de lancer, après avoir modifié l’image dans docker-compose.yml, jusqu’à ce que le container ait démarrer.
wait_migrations.sh : boucle sur la requête psql pour récupérer les jobs de migrations en cours.

Le travail consiste donc à boucler autour de :

modifier l’image docker avec la version de gitlab voulue
docker compose up puis attendre que le container Gitlab ait réellement démarré
Vérifier que les jobs de migration tournent, jusqu’à leur fin
Vérifier l’instance et ses différents éléments
Effectuer une sauvegarde

Et cela jusqu’à atteindre la version de Gitlab voulue.

Conclusion

Au cours de ces deux articles j’ai pu exposer la base de l’administration de Gitlab en auto-hébergé. Nous avons vu l’installation, l’ajout de runner, l’ajout d’utilisateurs en masse. Nous avons également vu la configuration HTTPS, la sauvegarde, la restauration et la migration.

Même si l’ensemble est assez lourd, les tâches sont individuellement assez simples. L’installation via Docker rend évidemment les choses plus simples.

Pour une installation de production, il faudra également bien vérifié la sécurité. Côté serveur, on peut s’appuyer sur le guide de l’ANSSI et sur les recommandations de Gitlab. Côté instance, Gitlab recommande toute une checkliste.

Installation, configuration, upgrade de Gitlab - partie 2