Un backup GitLab que vous ne pouvez pas restaurer n'est qu'un gros fichier

La plupart des instances GitLab auto-hébergées ont un job de backup nocturne, et la plupart des personnes qui l'ont mis en place n'ont jamais restauré à partir de lui. C'est un problème, parce que l'archive que GitLab produit est délibérément incomplète. Restaurez-la sur un serveur neuf sans les fichiers qu'elle laisse de côté, et vos dépôts reviennent tandis que vos variables CI, vos réglages d'authentification à deux facteurs et vos enregistrements de runners deviennent des données illisibles. Voici ce que contient un backup GitLab complet, comment le déplacer sans affaiblir votre sécurité, et comment prouver qu'il fonctionne.

Ce que la tâche de backup inclut, et ce qu'elle laisse de côté

Sur une installation par paquet (Omnibus), la tâche de backup est :

sudo gitlab-backup create STRATEGY=copy

Elle écrit une seule archive tar dans le répertoire de backup, en général /var/opt/gitlab/backups. Cette archive contient la base de données, les dépôts Git, les uploads, les objets LFS, les artifacts des jobs CI, les pages, les packages et, s'il est activé, le container registry. STRATEGY=copy copie les données avant de les archiver, ce qui évite des erreurs quand des fichiers changent pendant un long backup sur une instance chargée.

Ce qu'elle ne contient pas, à dessein :

• /etc/gitlab/gitlab-secrets.json, les clés qui chiffrent les colonnes sensibles de la base de données.
• /etc/gitlab/gitlab.rb, votre configuration.
• Les certificats et clés TLS sous /etc/gitlab/ssl, si vous les y conservez.
• Les clés d'hôte SSH dans /etc/ssh, que les clients de vos développeurs ont déjà enregistrées.

GitLab les laisse de côté pour qu'une seule archive volée ne contienne pas à la fois les données chiffrées et la clé qui les déchiffre. Le raisonnement est sain, et il vous confie la tâche de les sauvegarder séparément.

Pourquoi le fichier de secrets compte autant

Les variables CI/CD, les tokens d'enregistrement des runners, les graines d'authentification à deux facteurs, les mots de passe d'intégrations et plusieurs autres valeurs sont chiffrés dans la base de données avec des clés tirées de gitlab-secrets.json. Restaurez la base de données sans le fichier de secrets correspondant et GitLab démarre, les dépôts sont là, puis les pipelines échouent, les utilisateurs avec authentification à deux facteurs ne peuvent plus se connecter, et les runners doivent être réenregistrés.

Sauvegardez le répertoire de configuration comme un artefact à part :

sudo gitlab-ctl backup-etc --backup-path /var/opt/gitlab/config-backups

Cela produit un tar de /etc/gitlab, fichier de secrets compris. Conservez-le à un autre endroit que l'archive de données, sous un accès plus strict, et gardez les paires correspondantes ensemble dans votre politique de rétention. Une archive de données du lundi et un fichier de secrets du jeudi peuvent ne pas s'accorder si quelque chose a été renouvelé entre-temps.

Pour les installations en conteneur, les commandes sont les mêmes, exécutées dans le conteneur, et /etc/gitlab est le volume que vous lui avez associé. Assurez-vous que ce volume fait partie de ce que vous sauvegardez. Il est facile de ne sauvegarder que le volume de données.

Tirez le backup, ne le poussez pas

Le schéma habituel est un cron sur le serveur GitLab qui copie l'archive vers un hôte de backup. Cela signifie que le serveur GitLab détient des identifiants qui peuvent écrire dans vos backups. Si GitLab est compromis, le moyen d'atteindre et de supprimer les backups l'est aussi.

Inversez le sens. L'hôte de backup se connecte à GitLab et récupère les fichiers. GitLab ne détient aucun identifiant pour l'hôte de backup et n'a aucun chemin réseau vers lui. Côté GitLab, limitez ce que la clé de l'hôte de backup peut faire avec une commande forcée dans authorized_keys :

command="/usr/local/bin/backup-send",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-ed25519 AAAA... backup-puller

où backup-send est un petit script qui ne fait rien d'autre qu'envoyer la plus récente archive de données et son archive de configuration correspondante. Sur l'hôte de backup, le job récupère les deux, vérifie leurs tailles et leurs sommes de contrôle, et alerte si l'une manque ou est plus ancienne que prévu.

Puis imposez le sens au firewall : l'hôte de backup peut ouvrir des connexions vers GitLab, rien sur le réseau de GitLab ne peut ouvrir de connexion vers l'hôte de backup.

Les règles de restauration à connaître avant d'en avoir besoin

Un backup GitLab ne se restaure que sur la même version et la même édition de GitLab que celles qui l'ont créé. Inscrivez la version dans le nom de l'archive ou dans un fichier annexe au moment du backup :

sudo gitlab-rake gitlab:env:info > gitlab-env-$(date +%F).txt

Si vous perdez le serveur et que le seul installeur que vous trouvez est plus récent, vous installerez d'abord l'ancienne version, restaurerez, puis mettrez à niveau en suivant le chemin pris en charge. Le savoir à l'avance transforme une longue nuit en procédure planifiée.

La restauration elle-même, sur une installation neuve de la version correspondante :

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# put gitlab-secrets.json and gitlab.rb back into /etc/gitlab first
sudo gitlab-ctl reconfigure
sudo gitlab-backup restore BACKUP=<archive-id>
sudo gitlab-ctl restart
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake gitlab:doctor:secrets

La dernière commande est celle qui compte. gitlab:doctor:secrets parcourt les colonnes chiffrées et signale celles qu'il ne peut pas déchiffrer. S'il signale des échecs, votre fichier de secrets et votre archive de données ne vont pas ensemble.

Prouvez-le selon un calendrier

Une restauration que vous n'avez pas testée est un espoir. Faites-en une routine :

1. Construisez une VM jetable sur un réseau isolé sans route vers la production.
2. Installez la version de GitLab enregistrée avec le backup.
3. Restaurez la paire configuration et données la plus récente.
4. Exécutez gitlab:check et gitlab:doctor:secrets.
5. Clonez un dépôt connu, comparez son dernier hash de commit avec la production, et ouvrez la page des variables CI d'un projet.
6. Enregistrez le résultat et le temps que cela a pris, puis détruisez la VM.

Chronométrez-le, aussi. La durée de la restauration est votre vrai temps de reprise, et elle est en général plus longue que ce que les gens imaginent sur une grande instance.

Une seconde copie indépendante du code

Le backup complet protège toute l'application. Pour les dépôts eux-mêmes, un simple miroir vous donne une seconde copie qui ne dépend pas du tout de l'outillage de GitLab :

git clone --mirror git@gitlab.example.com:group/project.git
git -C project.git remote update --prune

Lancez-le depuis le côté backup pour les dépôts que vous ne pouvez pas vous permettre de perdre. Il ne restaurera pas les issues ni les merge requests, mais il signifie que l'historique de votre code survit même à une archive de backup que vous ne pouvez pas lire.

La version courte

• gitlab-backup create est la moitié d'un backup. gitlab-ctl backup-etc est l'autre moitié.
• Gardez secrets et données en paires correspondantes, stockées séparément, avec un accès plus strict sur les secrets.
• Le côté backup tire. GitLab n'a aucun chemin vers ses propres backups.
• Enregistrez la version de GitLab avec chaque archive.
• Restaurez selon un calendrier, et exécutez gitlab:doctor:secrets à chaque fois.

C'est ainsi que nous protégeons les instances GitLab que nous exploitons pour nos clients dans nos propres datacenters. Si vous souhaitez faire vérifier votre propre chemin de restauration, nous vous aiderons volontiers.

Parler à un ingénieur

related line: Voir aussi : Gestion de sources infogérée sur GitLab · Documents bureautiques infogérés sur Nextcloud

footer line: Publié le 22 octobre 2026. Toutes les notes de terrain