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 MIT, 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 représente la solution la plus légère du marché. 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 ; Forgejo au repos consomme environ 80 Mo. 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. Dans *Administration du site → Paramètres → Utilisateurs*, décochez « Autoriser l'inscription d'utilisateurs ». 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é*. Forcez la 2FA pour l'ensemble des utilisateurs via le paramètre REQUIRE_SIGNIN_VIEW et les politiques de sécurité organisationnelle.

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é, configurez la visibilité par défaut sur *Privé* dans les paramètres d'organisation. Les tokens d'accès pour publier doivent avoir une portée minimale (packages:write 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.

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

Forge exécute ses migrations automatiquement au démarrage. Vérifiez que la ligne Finished successfully apparaît dans les logs. En cas d'erreur de migration, restaurez la sauvegarde SQL et signalez le problème sur le tracker Forgejo. Consultez les notes de version avant chaque saut de version majeure — les migrations entre versions majeures peuvent nécessiter une étape intermédiaire.

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 → Dépôts → Git Repositories → Run Git GC*. Pour automatiser, configurez la tâche planifiée dans app.ini sous [cron.run_task].