Comment auto-héberger Gitea en 2026 : dépôts, SSH et mises à niveau fiables

Si vous avez déjà essayé d’auto-héberger Gitea, vous connaissez probablement cette situation frustrante : l’interface s’affiche, mais ROOT_URL génère des liens de clonage localhost ou le port SSH n’est pas redirigé. Recréer le conteneur suffit rarement à résoudre un désaccord entre les URL, l’état du système et les dépendances.

Ce guide s’appuie sur un critère de validation concret : cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément. Chaque choix de configuration est évalué par rapport à ce critère, et non à la présence d’un badge de conteneur vert.

Identifiez chaque donnée persistante de Gitea

Répertoriez l’état avant de créer le premier véritable enregistrement : dépôts, objets LFS, pièces jointes, configuration et base de données. Montez /data avant l’initialisation, écrivez quelques données d’exemple inoffensives, puis remplacez le conteneur pour vérifier que ce chemin est réellement persistant. Confirmez le montage en écrivant des données sans risque, en remplaçant Gitea, puis en les relisant.

Les snapshots sont utiles pour effectuer rapidement un rollback, mais une sauvegarde indépendante est nécessaire si l’hôte ou le volume disparaît. Effectuez une restauration dans un environnement vide avec l’image épinglée et vérifiez que les dépôts passent fsck, que les objets LFS se téléchargent et que les issues, releases et permissions utilisateur correspondent à l’état antérieur à la sauvegarde. Utilisez les volumes persistants et les snapshots pour bien distinguer ces deux mécanismes de récupération.

Construisez un conteneur Gitea remplaçable

La commande suivante rend la frontière du conteneur visible sans prétendre provisionner tous les services externes.

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__security__SECRET_KEY=replace-with-a-long-random-value \
  gitea/gitea:latest

Avant d’ouvrir l’ingress, inspectez l’environnement résolu, les montages et le listener. Ajoutez les paramètres de connexion validés pour Postgres ou MySQL dans le cas d’une installation plus importante, ainsi qu’une route SSH si nécessaire ; utilisez des noms privés pour les services privés. Un démarrage réussi se termine lorsque vous pouvez cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément, et non lorsque docker ps affiche Up.

Séparez Gitea de ses dépendances

Pour Gitea, la santé du processus et celle du produit sont deux sujets distincts. Le port 3000 peut répondre alors que la transaction côté utilisateur échoue toujours. Le contrat réseau de Gitea comprend Postgres ou MySQL dans le cas d’une installation plus importante, ainsi qu’une route SSH si nécessaire. Conservez les endpoints privés sur le DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à Gitea un identifiant de service limité.

Utilisez cet exercice de readiness après toute modification importante de la configuration : cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément. Évitez d’inclure des vérifications externes coûteuses dans les sondes de liveness afin qu’une panne de fournisseur ne provoque pas une boucle de redémarrage. Le travail de capacity planning doit suivre le nombre de dépôts, le packing des objets Git, le stockage LFS, la latence de la base de données et la charge des runners plutôt que les simples requêtes de pages, qui reflètent moins bien la pression réelle exercée sur Gitea.

TLS est simple ; les URL générées, beaucoup moins

Exposez un seul hostname HTTPS pour Gitea et gardez le port brut 3000 privé. Définissez ROOT_URL et SSH_DOMAIN sur les adresses que les utilisateurs utilisent réellement pour cloner. Les navigateurs et les clients API ne découvriront ainsi pas deux adresses concurrentes.

Depuis un client vierge, exécutez la transaction validée et examinez la première requête qui échoue. Utilisez le guide des domaines personnalisés lorsque le DNS ou TLS est incorrect. Traitez « ROOT_URL génère des liens de clonage localhost ou le port SSH n’est pas redirigé » comme un diagnostic applicatif distinct une fois la route validée.

Validez le déploiement Gitea de bout en bout

Ne faites pas du trafic du premier utilisateur votre test d’acceptation pour Gitea. Préparez un état d’exemple inoffensif et exécutez l’action complète « cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément ». Notez l’URL publique exacte, le résultat, la référence de l’image et l’intervalle de logs associés à l’exécution.

Remplacez le conteneur et recommencez sans reconstruire les données. Récupérez ensuite l’installation sur un hôte vide ; la condition de récupération est que les dépôts passent fsck, que les objets LFS se téléchargent et que les issues, releases et permissions utilisateur correspondent à l’état antérieur à la sauvegarde. À chaque passage, observez le nombre de dépôts, le packing des objets Git, le stockage LFS, la latence de la base de données et la charge des runners plutôt que les simples requêtes de pages, puis définissez une alerte sur la dégradation de la transaction et non sur les métriques d’un conteneur inactif.

Une dernière vérification doit échouer volontairement : refusez temporairement à l’identité de test l’accès à Postgres ou MySQL dans le cas d’une installation plus importante, ainsi qu’à une route SSH si nécessaire. Vérifiez que le message Gitea obtenu identifie la frontière concernée au lieu de déclencher une suppression de données ou un redémarrage sans fin. Restaurez la condition valide et confirmez que la même transaction d’exemple réussit. Conservez cet exercice court dans la checklist de release.

Répétez la modification Gitea à risque

Pour Gitea, surveillez une transaction plutôt qu’un processus : cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément. Combinez sa latence et son taux d’erreur avec le nombre de dépôts, le packing des objets Git, le stockage LFS, la latence de la base de données et la charge des runners plutôt qu’avec les simples requêtes de pages, afin qu’une alerte identifie le composant saturé.

La répétition de la mise à niveau doit couvrir le fait que les migrations de schéma, les hooks de dépôt, les packages et les runners tiers nécessitent une mise à niveau Gitea progressive. Restaurez, migrez et exécutez la transaction avant de remplacer la version en production. Si ROOT_URL génère des liens de clonage localhost ou si le port SSH n’est pas redirigé, n’effacez pas les données pour obtenir un démarrage au vert ; comparez dans cet ordre la version, les variables, les montages et l’accessibilité des dépendances.

Protégez la partie précieuse de Gitea

Après la première connexion, vérifiez ce qu’un visiteur anonyme, un utilisateur standard et un administrateur peuvent chacun faire. Le problème Gitea à éviter est de laisser l’installateur ou le premier compte administrateur accessible plus longtemps que nécessaire. La politique attendue consiste à fermer l’installateur après l’initialisation, à restreindre l’administration du site et à utiliser des tokens d’enregistrement de runners à durée de vie courte.

Traitez GITEA__security__SECRET_KEY selon son rôle dans Gitea : gardez les valeurs sensibles hors de Git, documentez les effets d’une rotation et ne remplacez jamais une valeur d’exemple publique en production. Séparez les comptes de dépendances des comptes humains, refusez les flux sortants inutilisés lorsque c’est possible et plafonnez le travail influencé par le nombre de dépôts, le packing des objets Git, le stockage LFS, la latence de la base de données et la charge des runners plutôt que par les simples requêtes de pages.

Ce que Dockup devrait automatiser pour Gitea

Pour Gitea, Dockup peut créer la route et le certificat TLS, préserver les montages, fournir les secrets et placer Postgres ou MySQL dans le cas d’une installation plus importante, ainsi qu’une route SSH si nécessaire sur un réseau privé, tout en déployant sur Dockup ou sur des serveurs rattachés.

La release gate reste la transaction Gitea concrète : cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément. Vérifiez également la condition de restauration : les dépôts passent fsck, les objets LFS se téléchargent et les issues, releases et permissions utilisateur correspondent à l’état antérieur à la sauvegarde. Ces deux vérifications montrent si le déploiement fonctionne et s’il peut être récupéré.

Foire aux questions

De quoi Gitea a-t-il besoin pour un déploiement en production ?

Faites passer le conteneur Gitea sur le port 3000 via une seule origine HTTPS. Le prérequis réseau complémentaire est Postgres ou MySQL dans le cas d’une installation plus importante, ainsi qu’une route SSH si nécessaire. Ne considérez pas Gitea comme prêt tant que vous ne pouvez pas cloner via HTTPS et SSH, pousser un commit et un objet LFS, ouvrir une issue et exécuter un job sur un runner Actions enregistré séparément.

Quelles données Gitea doivent figurer dans une sauvegarde ?

Rendez /data persistant et incluez les dépôts, les objets LFS, les pièces jointes, la configuration et la base de données dans le même manifeste de récupération. Une restauration Gitea vierge n’est réussie que lorsque les dépôts passent fsck, que les objets LFS se téléchargent et que les issues, releases et permissions utilisateur correspondent à l’état antérieur à la sauvegarde.

Gitea nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine Gitea publique et conservez le port 3000 sur la route interne. Appliquez correctement le paramètre Gitea : définissez ROOT_URL et SSH_DOMAIN sur les adresses que les utilisateurs utilisent réellement pour cloner. Pour Gitea, HTTPS protège les identifiants ou le contenu utilisateur pendant leur transit et garantit un comportement cohérent des clients dépendant de l’origine.

Comment tester une mise à niveau Gitea ?

Restaurez l’état actuel de Gitea dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif, car les migrations de schéma, les hooks de dépôt, les packages et les runners tiers nécessitent une mise à niveau Gitea progressive. Conservez l’image Gitea précédente jusqu’à ce que les limites de migration des données et de rollback soient comprises.