Mettre à jour Forgejo

Mettre à jour Forgejo se résume à remplacer un binaire. Mais une mise à jour mal exécutée peut corrompre la base de données ou bloquer le service. Cette procédure, testée en lab avec Forgejo 14.0.3, garantit une mise à jour sécurisée en moins de 10 minutes.

La séquence est toujours la même : vider les queues → sauvegarder → arrêter → remplacer le binaire (avec vérification SHA256) → démarrer → lancer doctor check.

Comprendre le cycle de versions de Forgejo

Depuis la version 7.0.0, Forgejo suit le versioning sémantique (MAJEUR.MINEUR.PATCH) :

Type de version	Fréquence	Support
Stable	~toutes les 3 semaines	Durée d’un cycle
LTS (Long Term Support)	4 fois par an	15 mois
Experimental	En continu	Aucun

Glissez pour voir

Quelle version suivre ?

• Production → choisissez la dernière version LTS pour les correctifs de sécurité sur 15 mois.
• Test/lab → la dernière version Stable convient.
• Ne jamais utiliser Experimental en production.

Les versions LTS sont identifiées sur https://codeberg.org/forgejo/forgejo/releases par le tag lts.

Règles de mise à jour

Toujours mettre à jour par paliers

Ne jamais sauter une version majeure. Si vous êtes en v13.x et souhaitez passer en v15.x, passez d’abord par v14.x, lancez doctor check --all, vérifiez que tout est OK, puis montez en v15.x.

Les mises à jour de patch (ex. 14.0.3 → 14.0.4) sont toujours rétrocompatibles et peuvent être appliquées directement.

Procédure de mise à jour

1. Vérifier la version actuelle

   forgejo --version
   # Forgejo version 14.0.3+gitea-1.22.0 (release name 14.0.3) built with go1.25.8
   sudo systemctl status forgejo.service | grep Active

2. Vider les queues internes

   Forgejo utilise des files de messages internes pour traiter les tâches asynchrones (webhooks, emails, indexation). Les vider avant l’arrêt évite de perdre des opérations en cours.

   sudo -u git forgejo manager flush-queues \
     -w /var/lib/forgejo \
     -c /etc/forgejo/app.ini

   La commande répond Flushed en quelques secondes. Si elle échoue, le service n’est peut-être pas démarré — vérifiez avec sudo systemctl status forgejo.service.

3. Créer un backup pré-upgrade

   Arrêter le service avant le backup garantit la cohérence des données.

   sudo systemctl stop forgejo.service
   
   sudo -u git forgejo dump \
     -w /var/lib/forgejo \
     -c /etc/forgejo/app.ini \
     -f /var/lib/forgejo/backups/forgejo-pre-upgrade-$(date +%Y%m%d-%H%M).zip

   Vérifiez que le ZIP est bien créé :

   ls -lh /var/lib/forgejo/backups/forgejo-pre-upgrade-*.zip

4. Télécharger le nouveau binaire

   Remplacez NEW_VERSION par la version cible (ex. 14.1.0) :

   NEW_VERSION="14.1.0"
   BASE_URL="https://codeberg.org/forgejo/forgejo/releases/download/v${NEW_VERSION}"
   
   wget -O "/tmp/forgejo-${NEW_VERSION}" \
     "${BASE_URL}/forgejo-${NEW_VERSION}-linux-amd64"
   wget -O "/tmp/forgejo-${NEW_VERSION}.sha256" \
     "${BASE_URL}/forgejo-${NEW_VERSION}-linux-amd64.sha256"

5. Vérifier l’intégrité du binaire

   La vérification SHA256 confirme que le téléchargement est intact et non altéré.

   cd /tmp
   sha256sum -c "forgejo-${NEW_VERSION}.sha256"
   # forgejo-14.1.0-linux-amd64: OK

   Si la vérification échoue (FAILED), relancez le téléchargement. Ne jamais déployer un binaire dont la somme de contrôle ne correspond pas.

6. Remplacer le binaire

   Le service est déjà arrêté depuis l’étape 3. Remplacez le binaire en place :

   sudo cp "/tmp/forgejo-${NEW_VERSION}" /usr/local/bin/forgejo
   sudo chmod 755 /usr/local/bin/forgejo
   
   # Confirmer la version installée
   forgejo --version

7. Démarrer le service

   sudo systemctl start forgejo.service
   
   # Attendre quelques secondes pour les migrations de base de données
   sleep 5
   sudo systemctl status forgejo.service

   Migrations automatiques

   Lors du premier démarrage après une mise à jour, Forgejo applique automatiquement les migrations de schéma de base de données. Ce processus peut prendre de quelques secondes à quelques minutes selon le volume de données. Le service est indisponible pendant ce temps. Les logs journalctl -u forgejo.service -f affichent la progression.

8. Lancer le diagnostic complet

   forgejo doctor check vérifie l’intégrité de l’installation : hooks Git, permissions, cohérence de la base de données, dépôts Git, et plus encore.

   sudo -u git forgejo doctor check --all \
     -w /var/lib/forgejo \
     -c /etc/forgejo/app.ini

   Sur une instance saine, tous les contrôles s’affichent avec [OK]. Une instance au lab Forgejo 14.0.3 retourne 29 contrôles — tous marqués OK.

   En cas d’avertissement (non bloquant), rejouer avec --fix pour laisser Forgejo corriger automatiquement :

   sudo -u git forgejo doctor check --all --fix \
     -w /var/lib/forgejo \
     -c /etc/forgejo/app.ini

Contrôle de la mise à jour

# Version active
forgejo --version

# Service en cours
sudo systemctl is-active forgejo.service

# Accès HTTP
curl -sw "%{http_code}" http://localhost:3000/ -o /dev/null
# 200

# Logs récents sans erreur
sudo journalctl -u forgejo.service --no-pager -n 20

Rollback en cas de problème

Si le service ne redémarre pas ou si l’interface est inaccessible après la mise à jour :

1. Arrêter le service

   sudo systemctl stop forgejo.service

2. Réinstaller l’ancien binaire

   Si vous avez conservé l’ancien binaire (recommandé) :

   # Exemple : remettre la version 14.0.3
   sudo cp /tmp/forgejo-14.0.3-linux-amd64 /usr/local/bin/forgejo
   sudo chmod 755 /usr/local/bin/forgejo
   forgejo --version

3. Restaurer depuis le backup pré-upgrade

   Si les données ont été altérées, restaurez depuis le backup créé à l’étape 3 :

   /docs/services/devops/forgejo/sauvegarder-restaurer/

   # Voir le guide de restauration complet

4. Relancer le service

   sudo systemctl start forgejo.service
   curl -sw "%{http_code}" http://localhost:3000/ -o /dev/null

Dépannage

Le service démarre mais plante immédiatement

sudo journalctl -u forgejo.service -n 50 --no-pager

Causes fréquentes après une mise à jour :

Message	Cause	Solution
database migration failed	Migration interrompue	Restaurer le backup pré-upgrade, puis réessayer
incompatible configuration	Clé app.ini supprimée dans la nouvelle version	Consulter le changelog Forgejo
permission denied	Droits du binaire incorrects	sudo chmod 755 /usr/local/bin/forgejo

Glissez pour voir

forgejo doctor check retourne des erreurs

Les warnings (non bloquants) peuvent souvent être résolus automatiquement :

sudo -u git forgejo doctor check --all --fix \
  -w /var/lib/forgejo \
  -c /etc/forgejo/app.ini

Pour les erreurs persistantes, augmentez le niveau de log pour le diagnostic :

# Dans /etc/forgejo/app.ini
[log]
LEVEL = Debug

Relancez le service et reprovoquez l’erreur, puis consultez les logs :

sudo journalctl -u forgejo.service --no-pager | grep -i "error\|fatal"

Remettez LEVEL = Info après le diagnostic.

À retenir

• La mise à jour Forgejo = remplacer un binaire unique (pas de paquets apt à gérer)
• Toujours vérifier le SHA256 avant de déployer un nouveau binaire
• La séquence sécurisée : flush-queues → dump → stop → binaire → start → doctor check
• Ne jamais sauter une version majeure (ex. de v13 à v15 : passer par v14 d’abord)
• forgejo doctor check --all exécute 29 contrôles d’intégrité — tous doivent être OK
• Conserver le backup pré-upgrade jusqu’à confirmation que la nouvelle version est stable

Prochaines étapes

Sauvegarder et restaurer Forgejo Maîtriser forgejo dump pour les backups complets et les rollbacks.

Configuration initiale Optimiser app.ini pour la production : logs, notifications, sécurité.

×

📖 Voir la documentation →