Gitea : sauvegarde et restauration

Sauvegarder Gitea, c’est sauvegarder les dépôts, la base de données et la configuration. Une sauvegarde n’a de valeur que testée : restaurer régulièrement sur une machine d’essai.

Sauvegarde avec gitea dump

sudo mkdir -p /var/backups/gitea
sudo chown git:git /var/backups/gitea
cd /tmp && sudo -u git gitea dump --config /etc/gitea/app.ini --file /var/backups/gitea/gitea-dump-$(date +%F).zip

La commande peut s’exécuter pendant que Gitea fonctionne. Options utiles :

Option	Rôle
--file, -f	Fichier de sortie (- : sortie standard)
--type tar.zst	Format (zip, tar, tar.gz, tar.xz, tar.zst…) : tar.zst est rapide et compact
--tempdir /var/tmp	Dossier temporaire sur disque (sur Ubuntu 26.04, /tmp est en mémoire)
--skip-repository	Sans les dépôts (base et configuration seulement)
--skip-log, --skip-index, --skip-attachment-data, --skip-lfs-data, --skip-package-data	Ignore ces éléments (réduit la taille)
--database postgres	Écrit le fichier SQL pour un autre moteur (migration)
--verbose	Détails du déroulement

Contenu de l’archive

Élément	Contenu
app.ini	Configuration
data/	Données de Gitea : fichier de base SQLite (data/gitea.db), pièces jointes, avatars, index, clés
gitea-db.sql	Export SQL de la base de données
repos/	Dépôts Git (un dossier par propriétaire)
custom/	Personnalisations (si présentes)

Note

Sur une instance vide (aucun dépôt), gitea dump peut échouer avec « Failed to include repositories : no such file or directory » : créer un premier dépôt, ou ajouter --skip-repository.

Planifier avec cron

Script /usr/local/bin/sauvegarde-gitea.sh :

#!/usr/bin/env bash
set -euo pipefail

DEST="/var/backups/gitea"
cd /tmp

sudo -u git gitea dump --config /etc/gitea/app.ini --type tar.zst \
  --tempdir /var/tmp --file "$DEST/gitea-$(date +%F_%H%M).tar.zst"

# Conserve 14 jours
find "$DEST" -name "gitea-*.tar.zst" -mtime +14 -delete

sudo chmod 750 /usr/local/bin/sauvegarde-gitea.sh
sudo crontab -e

30 3 * * * /usr/local/bin/sauvegarde-gitea.sh >> /var/log/sauvegarde-gitea.log 2>&1

Copier ensuite les archives hors du serveur. L’archive contient app.ini (secrets, mots de passe) : la stocker avec des droits restreints (chmod 600) et la chiffrer si elle quitte le serveur.

Restaurer

Il n’existe pas de commande de restauration automatique : on remet chaque élément à sa place. Procédure sur un serveur où Gitea est installé (voir Installation), avec la même version de Gitea (ou plus récente) que celle de la sauvegarde.

sudo systemctl stop gitea
mkdir /tmp/restauration && cd /tmp/restauration
unzip /var/backups/gitea/gitea-dump-2026-10-05.zip           # (tar xf … pour un .tar.zst)

sudo cp app.ini /etc/gitea/app.ini
sudo rm -rf /var/lib/gitea/data
sudo cp -a data /var/lib/gitea/data                          # contient data/gitea.db (base SQLite)
sudo mkdir -p /var/lib/gitea/data/gitea-repositories
sudo cp -a repos/. /var/lib/gitea/data/gitea-repositories/
sudo chown -R git:git /var/lib/gitea
sudo chown root:git /etc/gitea/app.ini && sudo chmod 640 /etc/gitea/app.ini

Adapter les chemins de app.ini si l’arborescence est différente ([repository] ROOT, [database] PATH). Puis :

sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea admin regenerate hooks
sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea admin regenerate keys
sudo systemctl start gitea
sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea doctor check --all --fix

Attention

Restaurer la base SQLite en copiant data/gitea.db (comme ci-dessus), plutôt qu’en important gitea-db.sql avec l’outil sqlite3 : le fichier SQL peut utiliser la fonction unistr(), absente du sqlite3 fourni par Ubuntu (version 3.45 sur 24.04, 3.46 sur 26.04). L’import produit alors l’erreur no such function: unistr.

Vérifier une sauvegarde

unzip -l /var/backups/gitea/gitea-dump-2026-10-05.zip | tail -5
unzip -p gitea-dump-2026-10-05.zip data/gitea.db > /tmp/verif.db
sqlite3 /tmp/verif.db "PRAGMA integrity_check; SELECT lower_name FROM user;"
unzip -l gitea-dump-2026-10-05.zip | grep "repos/" | head -5

Le test définitif est une restauration complète sur une machine d’essai, suivie de doctor check --all.

Sauvegarde de la base seule

Pour une copie rapide de la base SQLite, sans arrêter Gitea :

sudo -u git sqlite3 /var/lib/gitea/data/gitea.db ".backup '/var/backups/gitea/gitea-$(date +%F).db'"

Voir SQLite : sauvegarde et maintenance. Cette copie ne contient pas les dépôts : elle complète gitea dump, elle ne le remplace pas.

Migrer vers PostgreSQL

Quand l’instance grandit, passer de SQLite à PostgreSQL (voir PostgreSQL : installation). Principe, à tester d’abord sur une copie :

1. Créer un rôle et une base PostgreSQL pour Gitea (voir Rôles et droits).

2. Exporter la base au format PostgreSQL :

   cd /tmp && sudo -u git gitea dump --config /etc/gitea/app.ini --database postgres --skip-repository --skip-log --skip-index --skip-attachment-data --file /var/tmp/gitea-pg.zip
   unzip -p /var/tmp/gitea-pg.zip gitea-db.sql > /var/tmp/gitea-db-pg.sql

3. Arrêter Gitea, importer dans PostgreSQL :

   sudo systemctl stop gitea
   psql -h 127.0.0.1 -U gitea -d gitea -f /var/tmp/gitea-db-pg.sql

4. Modifier la section [database] de app.ini (DB_TYPE = postgres, HOST, NAME, USER, PASSWD), puis sudo systemctl start gitea et doctor check --all.

L’import du fichier SQL au format PostgreSQL a été vérifié sur PostgreSQL 18 (tables et utilisateurs repris sans erreur) ; conserver l’ancienne base SQLite intacte jusqu’à validation complète.

Dépannage

Symptôme	Piste
gitea dump : permission denied	Exécuter avec sudo -u git depuis un dossier accessible (cd /tmp)
no such function: unistr	Voir l’avertissement de la restauration : copier data/gitea.db
Les pushs échouent après restauration	admin regenerate hooks
Connexion SSH refusée après restauration	admin regenerate keys
Erreurs de droits après restauration	sudo chown -R git:git /var/lib/gitea
Archive très volumineuse	--skip-index, --skip-log, --type tar.zst ; nettoyer les anciennes archives

Pour aller plus loin

• Documentation : Backup and Restore
• Planification : Bonnes pratiques Bash

Dans la même rubrique

• Installation
• Configuration
• Administration en ligne de commande
• Dépôts, accès et API
• Sauvegarde et restauration
• Mise à jour et maintenance
• Gitea Actions (CI)