Gitea : mise à jour et maintenance

Mettre à jour et entretenir une instance Gitea avec SQLite. Les exemples utilisent les chemins de l’installation par binaire (/usr/local/bin/gitea, /var/lib/gitea).

Mettre à jour

Les migrations de base de données s’exécutent automatiquement au démarrage de la nouvelle version, et ne sont pas réversibles : la sauvegarde est indispensable.

# 1. Sauvegarde (voir « Sauvegarde et restauration »)
cd /tmp && sudo -u git gitea dump --config /etc/gitea/app.ini --tempdir /var/tmp --file /var/backups/gitea/avant-maj-$(date +%F).zip

# 2. Télécharger et vérifier la nouvelle version
VERSION=28.0.0
cd /tmp
curl -fsSLO "https://dl.gitea.com/gitea/${VERSION}/gitea-${VERSION}-linux-amd64"
curl -fsSLO "https://dl.gitea.com/gitea/${VERSION}/gitea-${VERSION}-linux-amd64.sha256"
sha256sum -c "gitea-${VERSION}-linux-amd64.sha256"

# 3. Remplacer le binaire
sudo systemctl stop gitea
sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.ancienne
sudo install -m 755 "gitea-${VERSION}-linux-amd64" /usr/local/bin/gitea
gitea --version

# 4. Redémarrer et contrôler
sudo systemctl start gitea
sudo journalctl -u gitea -n 30 --no-pager
curl -s http://127.0.0.1:3000/api/v1/version
sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea doctor check --all

Vérifier aussi la signature GPG, comme dans Installation.

Revenir en arrière

Une nouvelle version peut avoir modifié la base : remettre l’ancien binaire ne suffit pas. Restaurer aussi la sauvegarde faite avant la mise à jour :

sudo systemctl stop gitea
sudo cp /usr/local/bin/gitea.ancienne /usr/local/bin/gitea
# puis restaurer la sauvegarde « avant-maj » (voir « Sauvegarde et restauration »)
sudo systemctl start gitea

Notes de version : Gitea 28

Gitea est passé de la série 1.26 à la version 28.0.0 (fin septembre 2026). À lire avant la mise à jour : github.com/go-gitea/gitea/releases. Changements signalés comme incompatibles dans les notes de la 28.0 :

les opérations réseau de Git passent par un proxy interne, avec des réglages de sortie (egress) mis à jour : vérifier les accès sortants du serveur (miroirs, migrations, webhooks) après la mise à jour ;
Gitea Actions : l’option RUN_RETENTION_DAYS permet de supprimer les anciens runs : vérifier la durée de conservation souhaitée.

Une version de sécurité est à installer rapidement : suivre les annonces du projet.

Journaux et surveillance

sudo systemctl status gitea
sudo journalctl -u gitea -f
sudo journalctl -u gitea -p err --since "1 day ago"
sudo tail -f /var/lib/gitea/log/gitea.log

Contrôle de santé pour une supervision (réponse 200) :

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/api/healthz

Diagnostic

gitea-cli doctor check --all             # à lancer après une mise à jour ou une restauration
gitea-cli doctor check --all --fix

(gitea-cli est l’alias défini dans Administration.)

Tâches planifiées de Gitea

Gitea exécute des tâches périodiques (nettoyage des archives, ramasse-miettes des dépôts, synchronisation des miroirs…). Les consulter et les lancer à la main : interface d’administration, Administration du site, Surveillance, Tâches planifiées. Réglages dans app.ini :

[cron.archive_cleanup]
ENABLED = true
SCHEDULE = @midnight
OLDER_THAN = 24h

[cron.repo_health_check]
ENABLED = true
SCHEDULE = @midnight

Entretenir SQLite

Pour une instance qui dure : mode WAL (voir Configuration), et une maintenance occasionnelle avec le service arrêté :

sudo systemctl stop gitea
sudo -u git sqlite3 /var/lib/gitea/data/gitea.db "PRAGMA integrity_check; PRAGMA optimize; VACUUM;"
sudo systemctl start gitea

VACUUM reconstruit le fichier (libère l’espace des suppressions) et demande, pendant l’opération, autant d’espace libre que la taille de la base.

Quand quitter SQLite ?

Signe	Action
Erreurs fréquentes `database is locked` malgré le mode WAL	Passer à PostgreSQL (voir Sauvegarde et restauration)
Nombreux utilisateurs actifs en même temps	Idem
Besoin de haute disponibilité ou de réplication	Idem

Espace disque

sudo du -sh /var/lib/gitea/data/* | sort -h
sudo du -sh /var/lib/gitea/data/gitea-repositories/* | sort -h | tail -5
df -h /var/lib/gitea

Réduire l’espace : suppression des anciens runs et artefacts d’Actions, nettoyage des archives (tâche planifiée), git gc sur les gros dépôts (interface : Dépôt, Paramètres, Exécuter le ramasse-miettes ; ou tâche repo_health_check).

Gérer le service

sudo systemctl restart gitea
sudo systemctl stop gitea
sudo systemctl disable gitea

Pour une maintenance sans coupure brutale : gitea-cli manager shutdown (arrêt propre), puis redémarrer le service.

Sécurité courante

Mettre à jour Gitea et le système (sudo apt update && sudo apt upgrade).
DISABLE_REGISTRATION = true, double authentification, jetons limités.
Port 3000 fermé au public (Caddy en frontal) ; sauvegardes testées et copiées hors du serveur.
Surveiller les journaux de connexion échouée (journalctl -u gitea) ; Fail2ban peut bloquer les attaques répétées (voir Ubuntu Server : actions après l’installation).

Dépannage

Symptôme	Piste
Gitea ne redémarre pas après la mise à jour	`journalctl -u gitea -n 50` ; restaurer l’ancien binaire et la sauvegarde
`database is locked`	Mode WAL, `SQLITE_TIMEOUT`, éviter de verrouiller la base pendant les sauvegardes
Interface lente	Espace disque, mémoire (`free -h`), taille de la base, files d’attente (`manager flush-queues`)
Disque plein	Supprimer anciens runs et archives, `git gc`, étendre le disque
Miroirs ou webhooks qui échouent (Gitea 28)	Vérifier les réglages de sortie (`egress`) et le proxy interne signalés dans les notes de version

Pour aller plus loin

Documentation : Upgrade from binary
Suite : Gitea Actions (CI)