Sauvegarder et restaurer GitLab

Une instance GitLab sans backup est une instance que vous perdrez tôt ou tard. La commande gitlab-backup create crée une archive complète de tous vos projets, issues, merge requests, CI/CD, et données utilisateurs. Ce guide couvre le backup complet, le stockage distant (S3/MinIO), et la procédure de restauration testée.

Ce que sauvegarde (et ne sauvegarde pas) gitlab-backup

C’est la source d’erreur la plus fréquente : gitlab-backup create ne sauvegarde pas tout.

Contenu	Sauvegardé par gitlab-backup	À sauvegarder séparément
Dépôts Git (projets + wikis)	✅
Base de données (issues, MR, users…)	✅
Pièces jointes, uploads	✅
Artifacts CI/CD	✅ (si non externalisé)
Terraform states	✅
CI Secure Files	✅
Container Registry	❌ [DISABLED] par défaut	Copier /var/opt/gitlab/gitlab-rails/shared/registry/
/etc/gitlab/gitlab.rb	❌	Obligatoire
/etc/gitlab/gitlab-secrets.json	❌	Obligatoire
Certificats TLS personnalisés	❌	Copier /etc/gitlab/trusted-certs/

Glissez pour voir

Sans gitlab-secrets.json, pas de restauration possible

Le fichier gitlab-secrets.json contient les clés qui chiffrent les variables CI/CD, les tokens 2FA, les webhooks… Si vous restaurez un backup sur un serveur sans ce fichier (ou avec un fichier différent), les données chiffrées seront irrécupérables.

Sauvegardez ces deux fichiers séparément et hors du serveur :

• /etc/gitlab/gitlab.rb
• /etc/gitlab/gitlab-secrets.json

Créer une sauvegarde manuelle

sudo gitlab-backup create

Progression (capturé en lab sur GitLab 18.10.1) :

2026-03-28 17:39:09 UTC -- Dumping database ...
2026-03-28 17:39:09 UTC -- Dumping PostgreSQL database gitlabhq_production ...
2026-03-28 17:39:10 UTC -- [DONE]
2026-03-28 17:39:10 UTC -- Dumping database ... done
2026-03-28 17:39:10 UTC -- Dumping repositories ...
2026-03-28 17:39:11 UTC -- Dumping repositories ... done
2026-03-28 17:39:11 UTC -- Dumping uploads ... done
2026-03-28 17:39:11 UTC -- Dumping builds ... done
2026-03-28 17:39:11 UTC -- Dumping artifacts ... done
2026-03-28 17:39:11 UTC -- Dumping pages ... done
2026-03-28 17:39:11 UTC -- Dumping lfs objects ... done
2026-03-28 17:39:11 UTC -- Dumping terraform states ... done
2026-03-28 17:39:11 UTC -- Dumping container registry images ... [DISABLED]
2026-03-28 17:39:11 UTC -- Dumping packages ... done
2026-03-28 17:39:11 UTC -- Dumping ci secure files ... done
2026-03-28 17:39:11 UTC -- Dumping external diffs ... done
2026-03-28 17:39:11 UTC -- Creating backup archive: 1774719549_2026_03_28_18.10.1_gitlab_backup.tar ... done
2026-03-28 17:39:11 UTC -- Warning: Your gitlab.rb and gitlab-secrets.json files contain sensitive data
                           and are not included in this backup. You will need these files to restore a backup.
                           Please back them up manually.
2026-03-28 17:39:11 UTC -- Backup 1774719549_2026_03_28_18.10.1 is done.

Le fichier créé suit le format : {TIMESTAMP}_{DATE}_{VERSION}_gitlab_backup.tar

Avertissement git.rb et gitlab-secrets.json

GitLab affiche systématiquement un avertissement en fin de backup vous rappelant que gitlab.rb et gitlab-secrets.json ne sont pas inclus. C’est normal — à sauvegarder séparément.

Localisation :

sudo ls -lh /var/opt/gitlab/backups/
# → -rw------- 1 git git 72K Mar 28 17:39 1774719549_2026_03_28_18.10.1_gitlab_backup.tar

Les permissions rw------- (owner: git) sont normales. N’utilisez pas ls sans sudo depuis un compte non-root.

Les permissions rw------- (owner: git) sont normales.

Exclure les gros éléments

Sur des instances avec beaucoup d’artifacts ou de LFS, le backup peut prendre des heures. Excluez les éléments non critiques :

# Exclure artifacts CI/CD et fichiers LFS
sudo gitlab-backup create SKIP=builds,artifacts,lfs

# Options disponibles : db, uploads, builds, artifacts, lfs, registry, pages

Planifier les sauvegardes automatiques

Configuration dans gitlab.rb

/etc/gitlab/gitlab.rb

# Dossier de destination
gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"

# Rétention : 7 jours (604800 secondes)
gitlab_rails['backup_keep_time'] = 604800

Appliquer :

sudo gitlab-ctl reconfigure

Cron quotidien

sudo crontab -e

Backup quotidien à 2h du matin avec purge automatique des anciens backups :

# Backup GitLab quotidien — 2h du matin
0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1 >> /var/log/gitlab-backup.log 2>&1

# Sauvegarde des fichiers de config (secrets) — vers un dossier sécurisé
5 2 * * * cp /etc/gitlab/gitlab.rb /etc/gitlab/gitlab-secrets.json /mnt/backup/gitlab-config/ 2>&1

CRON=1 supprime les messages informatifs — seules les erreurs apparaissent dans les logs.

Stocker les backups à distance (S3 / MinIO)

Pour un stockage hors du serveur (recommandé en production), configurez une destination objet :

AWS S3

/etc/gitlab/gitlab.rb

gitlab_rails['backup_upload_connection'] = {
  'provider' => 'AWS',
  'region' => 'eu-west-1',
  'aws_access_key_id' => 'VOTRE_ACCESS_KEY',
  'aws_secret_access_key' => 'VOTRE_SECRET_KEY'
}
gitlab_rails['backup_upload_remote_directory'] = 'mon-bucket-gitlab-backups'
gitlab_rails['backup_keep_time'] = 604800  # 7 jours

MinIO (self-hosted)

/etc/gitlab/gitlab.rb

gitlab_rails['backup_upload_connection'] = {
  'provider' => 'AWS',
  'region' => 'us-east-1',
  'aws_access_key_id' => 'minioadmin',
  'aws_secret_access_key' => 'minioadmin',
  'endpoint' => 'http://minio.mondomaine.com:9000',
  'path_style' => true
}
gitlab_rails['backup_upload_remote_directory'] = 'gitlab-backups'

Après gitlab-ctl reconfigure, le prochain gitlab-backup create uploadera automatiquement vers l’objet store.

Garder aussi une copie locale

Même avec un stockage distant, gardez quelques backups locaux : ils sont plus rapides à restaurer. Configurez backup_keep_time pour ne pas saturer le disque.

Restaurer GitLab

Prérequis stricts pour la restauration

Avant de restaurer :

1. La version de GitLab doit être identique à celle du backup (même version mineure).
2. Les fichiers gitlab.rb et gitlab-secrets.json doivent être en place.
3. Le fichier de backup doit être dans /var/opt/gitlab/backups/ avec les permissions correctes.

1. Préparer le fichier de backup

   # Copier le backup dans le dossier attendu
   sudo cp 1743157890_2026_03_28_18.10.1_gitlab_backup.tar /var/opt/gitlab/backups/
   
   # Corriger les permissions
   sudo chown git:git /var/opt/gitlab/backups/1743157890_2026_03_28_18.10.1_gitlab_backup.tar
   sudo chmod 600 /var/opt/gitlab/backups/1743157890_2026_03_28_18.10.1_gitlab_backup.tar

2. Restaurer les fichiers de configuration

   Si c’est un nouveau serveur (pas le même que celui du backup) :

   # Copier depuis votre stockage sécurisé
   sudo cp gitlab.rb /etc/gitlab/gitlab.rb
   sudo cp gitlab-secrets.json /etc/gitlab/gitlab-secrets.json
   sudo chmod 600 /etc/gitlab/gitlab-secrets.json
   sudo gitlab-ctl reconfigure

3. Arrêter les services qui écrivent dans la base

   sudo gitlab-ctl stop puma
   sudo gitlab-ctl stop sidekiq
   
   # Vérifier que les services sont bien arrêtés
   sudo gitlab-ctl status

4. Lancer la restauration

   # Remplacer le timestamp par celui de votre backup
   sudo gitlab-backup restore BACKUP=1743157890_2026_03_28_18.10.1

   GitLab vous demande une confirmation avant d’écraser les données :

   Before restoring the database, we will remove all existing
   tables to avoid future upgrade problems. Be aware that if you have
   custom PostgreSQL extensions or trusted extensions whitelist,
   you will need to re-create them manually after restoring...
   
   Do you want to continue (yes/no)?

   Tapez yes.

5. Redémarrer et vérifier

   sudo gitlab-ctl restart
   
   # Vérifier la santé de l'installation
   sudo gitlab-rake gitlab:check SANITIZE=true
   
   # Vérifier la version
   sudo gitlab-rake gitlab:env:info

Vérifier qu’un backup est valide

Ne pas attendre une catastrophe pour tester vos sauvegardes. Vérification rapide :

# Lister les backups récents
ls -lh /var/opt/gitlab/backups/ | tail -5

# Vérifier le contenu d'un backup sans le restaurer
tar -tzf /var/opt/gitlab/backups/1743157890_2026_03_28_18.10.1_gitlab_backup.tar | head -20

Contenu attendu :

backup_information.yml
db/database.sql.gz
repositories/...
uploads.tar.gz
builds.tar.gz
artifacts.tar.gz
...

La présence de backup_information.yml et db/database.sql.gz confirme un backup valide.

À retenir

• gitlab-backup create ne sauvegarde pas gitlab.rb et gitlab-secrets.json — à sauvegarder séparément.
• La restauration nécessite la même version exacte de GitLab. Vérifiez avant de restaurer.
• Testez vos restaurations régulièrement (au moins une fois par trimestre sur un lab).
• CRON=1 dans la commande de backup supprime les messages informatifs pour un cron silencieux.
• Stocker les backups sur le même serveur que GitLab n’est pas une vraie stratégie de backup — utilisez un stockage distant ou une copie hors site.

Prochaines étapes

Mettre à jour GitLab Procédure de mise à jour mineure et majeure en sécurité.

Configuration initiale SMTP, inscriptions, SSH, paramètres essentiels post-installation.

GitLab Runner Ajouter un runner pour exécuter vos pipelines CI/CD.

×

📖 Voir la documentation →