Héberger Forgejo sur votre VPS : guide complet 2025

Forgejo est né en 2022 d'un fork de Gitea, motivé par des inquiétudes sur la gouvernance du projet. Son développement est entièrement communautaire, sous licence GPLv3+ depuis la v9.0 (août 2024 ; MIT auparavant), sans dépendance à une société commerciale. Pour les équipes qui veulent contrôler leur code source, leur pipeline CI/CD et leurs artefacts sans passer par GitHub, GitLab ou Bitbucket, Forgejo est l'une des solutions les plus légères. L'interface est familière pour tout développeur ayant utilisé GitHub, la migration depuis Gitea est transparente et la compatibilité avec les GitHub Actions simplifie l'adoption.

Avant de lancer Forgejo, dimensionnez votre VPS selon la taille réelle de votre équipe. Pour 1 à 5 développeurs avec quelques dizaines de dépôts, 1 vCPU et 1 Go de RAM suffisent. Pour 5 à 20 développeurs avec CI/CD active, prévoyez 2 vCPU et 2 Go de RAM. Au-delà de 20 développeurs ou pour des dépôts de grande taille (monorepos, binaires), 4 vCPU et 4 Go de RAM garantissent une expérience fluide. Côté stockage, comptez le volume de vos dépôts Git plus 20 % de marge pour les artefacts et les sauvegardes.

Sur le plan réseau, trois ports doivent être ouverts dans votre pare-feu : le port 80 (HTTP, pour la validation Let's Encrypt), le port 443 (HTTPS, trafic web) et le port 2222 (SSH Git, pour éviter le conflit avec le SSH d'administration sur 22). Côté logiciel, vous avez besoin de Docker Engine ≥ 24, Docker Compose v2 et d'un nom de domaine pointant vers votre VPS.

La compatibilité avec la syntaxe GitHub Actions est très large. Créez le fichier .forgejo/workflows/ci.yml à la racine de votre dépôt :

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          npm ci
          npm test

Les labels runs-on correspondent aux labels déclarés lors de l'enregistrement du runner. Vous pouvez définir plusieurs runners avec des labels différents (ex. arm64, gpu, high-memory) et cibler le bon environnement par job. Les artefacts et le cache fonctionnent avec les mêmes actions officielles que sur GitHub.

Un Forgejo fraîchement installé est fonctionnel mais pas durci. Voici les six points à traiter impérativement avant d'ouvrir la forge à votre équipe.

Désactiver l'inscription publique. Si vous ne l'avez pas fait dans l'assistant, ajoutez FORGEJO__service__DISABLE_REGISTRATION=true aux variables d'environnement du conteneur (ou DISABLE_REGISTRATION = true dans la section [service] de app.ini) : seul un administrateur peut alors créer des comptes. Sur une forge interne, personne ne doit pouvoir créer un compte sans invitation.

Activer la 2FA pour les administrateurs. Chaque compte admin doit activer l'authentification à deux facteurs dans *Paramètres → Sécurité*. Pour l'imposer, réglez GLOBAL_TWO_FACTOR_REQUIREMENT dans la section [security] de app.ini (admin pour les administrateurs, all pour tous les utilisateurs). Le paramètre REQUIRE_SIGNIN_VIEW, lui, oblige seulement à se connecter pour consulter la forge.

SSH par clé uniquement. Désactivez l'authentification par mot de passe dans /etc/ssh/sshd_config du serveur hôte (PasswordAuthentication no). Pour le SSH Git (port 2222), Forgejo n'accepte que les clés publiques enregistrées dans les profils utilisateurs — c'est son comportement par défaut.

Secrets de webhooks. Lors de la création de chaque webhook (vers votre CI externe, Slack, etc.), renseignez toujours le champ *Secret*. Forgejo signe la charge utile avec HMAC-SHA256 ; votre récepteur doit vérifier cette signature avant de traiter l'événement.

Packages privés. Si vous utilisez le registre de paquets intégré, rappelez-vous qu'un paquet hérite de la visibilité de son propriétaire : publiez-le sous une organisation ou un compte privé pour le réserver à ses membres. Les tokens d'accès pour publier doivent avoir une portée minimale (write:package uniquement, jamais un token admin global).

Pare-feu. Fermez tous les ports sauf 80, 443 et 2222. Le port 3000 (Forgejo interne) ne doit jamais être exposé directement ; il est consommé uniquement par le reverse proxy en loopback, d'où sa publication sur 127.0.0.1:3000 dans le compose. Un port publié par Docker contourne les règles ufw : seule cette liaison à 127.0.0.1 le garde hors d'Internet.

La procédure de mise à jour Docker est simple et ne nécessite que quelques secondes d'indisponibilité.

cd /opt/forgejo
# 1. Tirer la nouvelle image
docker compose pull forgejo

# 2. Sauvegarder la base avant toute migration
docker compose exec db pg_dump -U forgejo forgejo > backup-$(date +%Y%m%d).sql

# 3. Redémarrer le service
docker compose up -d forgejo

# 4. Vérifier les migrations de schéma
docker compose logs forgejo | grep -i migrat

Forgejo exécute ses migrations automatiquement au démarrage. Vérifiez que les logs ne signalent aucune erreur de migration. En cas d'erreur de migration, restaurez la sauvegarde SQL et signalez le problème sur le tracker Forgejo. Le tag 17 ne suit que les versions 17.x : pour passer à la version majeure suivante, changez le tag dans le compose après une sauvegarde complète, et consultez les notes de version avant chaque saut de version majeure. Forgejo refuse de démarrer sur une base plus récente que lui : le retour arrière passe par la restauration de la sauvegarde.

Connexion SSH refusée sur le port 2222. Vérifiez d'abord que le port est bien publié par Docker (docker compose ps → colonne Ports). Ensuite, testez depuis le client : ssh -p 2222 [email protected]. Si la réponse est PTY allocation request failed, la connexion fonctionne — Forgejo répond Hi <utilisateur>! You've successfully authenticated. Si vous obtenez Connection refused, le pare-feu bloque le port : ufw allow 2222/tcp.

Runner affiché offline dans l'interface. Le runner contacte Forgejo en HTTPS sortant. Vérifiez que le conteneur runner peut résoudre et atteindre git.mondomaine.com. Un certificat auto-signé nécessite de monter votre CA dans le conteneur. Redémarrez le runner après avoir corrigé la connectivité : docker compose restart runner.

Push rejeté par un hook pre-receive. Forgejo peut rejeter un push si un hook de protection de branche est actif (revue de code requise, tests CI obligatoires) ou si une règle de taille de fichier est dépassée. Le message d'erreur git contient le détail. Pour les gros binaires (> 100 Mo), utilisez Git LFS : Forgejo supporte le protocole LFS nativement.

Interface lente après plusieurs mois. Lancez le garbage collector Git sur les dépôts actifs depuis l'administration : *Administration du site → Tableau de bord → Opérations de maintenance*, tâche de nettoyage (garbage collection) des dépôts. Pour automatiser, activez la tâche planifiée [cron.git_gc_repos] dans app.ini (ENABLED = true ; elle tourne toutes les 72 h par défaut).