Mettre à jour Gitea

L’upgrade de Gitea se résume au remplacement du binaire : télécharger le nouveau, arrêter le service, copier, redémarrer. Avec un backup préventif et un gitea doctor check post-upgrade, la procédure est fiable et rapide.

Cette procédure a été testée sur Gitea 1.25.5 et convient pour les mises à jour de patch (1.25.x → 1.25.y) et les mises à jour mineures (1.25.x → 1.26.x).

Avant de commencer

Vérifiez la version actuelle et identifiez la cible :

gitea --version
# gitea version 1.25.5 built with GNU Make 4.3, go1.25.8 : bindata, sqlite, sqlite_unlock_notify

Consultez les releases Gitea pour identifier la dernière version stable et lire les notes de version.

Procédure d’upgrade

Vider les queues de traitement

Gitea utilise des queues internes pour traiter les webhooks, notifications et indexations. Les vider avant l’arrêt évite de perdre des événements en cours.
Fenêtre de terminal
```
sudo -u git GITEA_WORK_DIR=/var/lib/gitea \
  gitea manager flush-queues \
  --config /etc/gitea/app.ini
# Flushed
```

Créer un backup préventif

Un backup est obligatoire avant tout upgrade. Il permet un retour arrière immédiat si la nouvelle version présente un problème.

sudo -u git GITEA_WORK_DIR=/var/lib/gitea \
  gitea dump \
  --config /etc/gitea/app.ini \
  --work-path /var/lib/gitea \
  --file /var/lib/gitea/backups/gitea-pre-upgrade-$(date +%Y%m%d).zip \
  --type zip
echo "Backup terminé"

Télécharger le nouveau binaire

Remplacez NEW_VERSION par la version cible (ex. 1.26.0).

NEW_VERSION="1.26.0"
cd /tmp

wget -O gitea-${NEW_VERSION}-linux-amd64 \
  https://github.com/go-gitea/gitea/releases/download/v${NEW_VERSION}/gitea-${NEW_VERSION}-linux-amd64
wget -O gitea-${NEW_VERSION}-linux-amd64.sha256 \
  https://github.com/go-gitea/gitea/releases/download/v${NEW_VERSION}/gitea-${NEW_VERSION}-linux-amd64.sha256

# Vérifier l'intégrité
sha256sum -c gitea-${NEW_VERSION}-linux-amd64.sha256
# gitea-x.x.x-linux-amd64: OK

Sauvegarder l’ancien binaire

Gardez le binaire actuel pour un rollback immédiat si nécessaire.
Fenêtre de terminal
```
sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.backup-$(date +%Y%m%d)
```
Arrêter le service
Fenêtre de terminal
```
sudo systemctl stop gitea.service
```

Remplacer le binaire

sudo cp /tmp/gitea-${NEW_VERSION}-linux-amd64 /usr/local/bin/gitea
sudo chmod 755 /usr/local/bin/gitea

# Vérifier la nouvelle version
gitea --version
# gitea version x.x.x ...

Redémarrer le service

sudo systemctl start gitea.service
sleep 5

# Vérifier que le service est actif
sudo systemctl is-active gitea.service
# active

Vérifier l’état post-upgrade

# Test de l'interface web
curl -o /dev/null -s -w "%{http_code}\n" http://localhost:3000/
# 200

# Test de l'API
curl -sf -u monadmin:'MotDePasse' \
  http://localhost:3000/api/v1/version \
  | python3 -c "import sys,json; print('Version API:', json.load(sys.stdin)['version'])"

Exécuter le doctor check

Le doctor check vérifie l’intégrité complète de l’installation après l’upgrade.
Fenêtre de terminal
```
sudo -u git GITEA_WORK_DIR=/var/lib/gitea \
  gitea doctor check --all \
  --config /etc/gitea/app.ini 2>&1
```
Un résultat propre ressemble à :
```
[1] Check paths and basic configuration
OK
[2] Check if GITEA_CUSTOM is set
OK
...
All done (checks: 28).
```
Aucune ligne [E] (erreur) ne doit apparaître. Les [W] (avertissements) sont souvent bénins (ex. répertoire custom non créé).

Rollback

Si la nouvelle version présente un problème, revenez à l’ancienne en quelques secondes :

sudo systemctl stop gitea.service
sudo cp /usr/local/bin/gitea.backup-$(date +%Y%m%d) /usr/local/bin/gitea
sudo chmod 755 /usr/local/bin/gitea
sudo systemctl start gitea.service

gitea --version    # Confirme l'ancienne version

Si le problème est plus grave (base de données corrompue), restaurez depuis le backup préventif créé à l’étape 2 — consultez le guide Sauvegarder et restaurer.

Vérifier les migrations de base de données

Certaines versions de Gitea incluent des migrations automatiques de schéma au démarrage. Ces migrations s’exécutent automatiquement lors du premier démarrage du nouveau binaire.

Pour vérifier dans les logs :

sudo journalctl -u gitea --since "5 minutes ago" --no-pager | grep -i 'migrat'

Les lignes [I] Running migration... et [I] Finished migration indiquent une migration réussie.

Automatiser les notifications de nouvelles versions

Gitea peut notifier les administrateurs lors de la disponibilité d’une nouvelle version :

# Dans /etc/gitea/app.ini
[other]
SHOW_FOOTER_VERSION          = true   # Affiche la version dans le pied de page
ENABLE_FEED                  = true

Vous pouvez aussi surveiller les releases via le flux RSS : https://github.com/go-gitea/gitea/releases.atom

À retenir

L’upgrade Gitea = remplacement du binaire — pas de migration de dépôts à faire manuellement
Toujours vider les queues avant l’arrêt : gitea manager flush-queues
Toujours sauvegarder avant l’upgrade : rollback = restauration du binaire + du backup
gitea doctor check --all confirme l’intégrité après chaque upgrade
Conserver le binaire précédent (gitea.backup-YYYYMMDD) pour 7 jours minimum

Prochaines étapes

Sauvegarder et restaurer Maîtriser gitea dump pour les backups quotidiens et la restauration.

Configuration initiale Optimiser app.ini pour la production.