Forgejo : la forge Git open source auto-hébergée

Le code source, les scripts d’exploitation, les playbooks et les fichiers de configuration sont devenus le cœur du patrimoine d’une DSI. Les confier à une plateforme SaaS américaine pose des questions de souveraineté, de conformité et de dépendance commerciale. Forgejo répond à ce besoin : c’est une forge logicielle libre, légère et auto-hébergée, qui offre l’essentiel de ce que l’on attend d’un GitHub ou d’un GitLab, sur votre propre infrastructure. Cet article présente son fonctionnement, son installation, ses usages et les bonnes pratiques pour l’exploiter sereinement.

Qu’est-ce que Forgejo ?

Forgejo (de l’espéranto forĝejo, « la forge ») est une plateforme d’hébergement de dépôts Git avec interface web. Elle regroupe dans un seul binaire les fonctions classiques d’une forge :

dépôts Git publics ou privés, accessibles en HTTPS et en SSH, avec gestion des branches protégées ;
tickets, jalons, étiquettes et tableaux de projet pour le suivi du travail ;
pull requests avec revue de code, commentaires en ligne et règles d’approbation ;
wiki par dépôt, registre de paquets (conteneurs, npm, PyPI, Maven…) et support de Git LFS ;
Forgejo Actions, un moteur d’intégration continue dont la syntaxe de workflows est proche de celle de GitHub Actions ;
miroirs et outils de migration depuis GitHub, GitLab, Gitea ou, depuis la version 17, Bitbucket Data Center.

Le projet est né fin 2022 comme fork de Gitea, après le passage de ce dernier sous le contrôle d’une société commerciale. En février 2024, Forgejo est devenu un fork à part entière (« hard fork ») qui suit désormais sa propre feuille de route. Ses domaines sont détenus par Codeberg e.V., une association à but non lucratif basée à Berlin, tandis que la gouvernance est définie collectivement par les contributeurs. Depuis la version 9.0, Forgejo est distribué sous licence GPL v3 ou ultérieure (les versions jusqu’à 8.0 étaient sous licence MIT).

Architecture et fonctionnement

Forgejo est écrit en Go et se présente sous la forme d’un binaire unique qui embarque le serveur web, le serveur SSH intégré (optionnel) et les tâches de fond. Son empreinte mémoire modeste lui permet de tourner sur une petite VM, voire sur un Raspberry Pi pour un usage de laboratoire.

Base de données : SQLite pour les petites installations, PostgreSQL ou MySQL/MariaDB en production.
Stockage : les dépôts Git sont de simples dépôts « bare » sur disque ; les pièces jointes, objets LFS et paquets peuvent être déportés sur un stockage compatible S3.
Configuration : un fichier app.ini, dont chaque clé peut aussi être définie par variable d’environnement au format FORGEJO__section__CLE.
CI/CD : Forgejo n’exécute pas lui-même les jobs. Il délègue cette tâche à un ou plusieurs Forgejo Runner, des agents installés sur d’autres machines qui récupèrent les workflows placés dans le répertoire .forgejo/workflows des dépôts.

Le rythme de publication est soutenu : une version majeure environ tous les trois mois, et des versions de maintenance au fil des correctifs. La version 17.0, publiée le 15 octobre 2026, est maintenue jusqu’au 28 janvier 2027 ; la branche LTS 15.0 est, elle, supportée jusqu’au 15 juillet 2027. En production, privilégiez une version LTS si vous ne souhaitez pas monter de version chaque trimestre.

Installation avec Docker Compose

Forgejo peut s’installer via un binaire, des paquets de distribution ou un conteneur. La méthode la plus simple à maintenir reste Docker avec Compose. L’image officielle est publiée sur le registre de Codeberg (codeberg.org/forgejo/forgejo), avec une variante rootless. L’exemple ci-dessous, issu de la documentation officielle, déploie Forgejo avec une base PostgreSQL : l’interface web écoute sur le port 3000 et le SSH du conteneur est exposé sur le port 222 de l’hôte.

mkdir -p /opt/forgejo && cd /opt/forgejo

cat > docker-compose.yml <<'EOF'
networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:17
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=MotDePasseRobuste
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=MotDePasseRobuste
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data
EOF

docker compose up -d
docker compose logs -f server

Le volume ./forgejo doit appartenir à l’UID/GID déclarés (1000 par défaut). Au premier accès sur http://serveur:3000, un assistant web propose de valider la configuration de la base, l’URL publique et le port SSH. En production, placez Forgejo derrière un reverse proxy avec un certificat TLS et renseignez l’URL HTTPS définitive (ROOT_URL) dès l’installation, car elle est utilisée dans les liens de clonage et les webhooks.

Prise en main et usages

Une fois l’instance en ligne, plusieurs tâches d’administration se font en ligne de commande avec l’outil forgejo, exécuté dans le conteneur sous l’utilisateur git : création du compte administrateur, vérification de l’intégrité de l’instance avec forgejo doctor check ou export complet avec forgejo dump.

Authentification centralisée. Forgejo sait déléguer l’authentification à un annuaire LDAP ou à un fournisseur OAuth2/OpenID Connect. Coupler l’instance à un IdP comme authentik permet d’imposer le MFA et de désactiver les comptes en un seul point lors d’un départ. Forgejo gère aussi nativement le TOTP et les clés de sécurité WebAuthn pour les comptes locaux.

Intégration continue. Forgejo Actions est activé par défaut. Il suffit d’enregistrer un runner auprès de l’instance (jeton disponible dans l’administration, au niveau de l’instance, d’une organisation ou d’un dépôt), puis de lui attribuer des étiquettes qui déterminent l’environnement d’exécution des jobs. Les workflows reprennent la syntaxe YAML de GitHub Actions, ce qui facilite la reprise de pipelines existants. Si vous découvrez ces notions, notre cours Introduction à la chaîne CI/CD pose les bases. Attention : un runner exécute du code arbitraire issu des dépôts, la documentation officielle le qualifie explicitement d’exécution de code à distance. Isolez-le sur une machine ou un réseau dédié.

Cas d’usage typiques en DSI : héberger les dépôts d’infrastructure as code et les playbooks d’automatisation, versionner les règles de détection et les configurations réseau, fournir un registre de conteneurs interne, ou maintenir des miroirs locaux de projets open source critiques pour ne plus dépendre de leur disponibilité en ligne.

Migration de l’existant. L’assistant « Nouvelle migration » importe un dépôt depuis GitHub, GitLab, Gitea, Bitbucket Data Center ou toute URL Git. Selon la source, il peut reprendre non seulement l’historique Git, mais aussi les tickets, pull requests, jalons, étiquettes, versions et wiki, à condition de fournir un jeton d’accès à la plateforme d’origine. Une approche progressive fonctionne bien : commencez par configurer des miroirs en lecture seule de vos dépôts les plus utilisés, laissez les équipes s’approprier l’interface, puis basculez définitivement dépôt par dépôt en mettant à jour les URL distantes des postes de travail et des pipelines.

Organisation des droits. Structurez l’instance par organisations (par exemple une pour l’infrastructure, une pour la sécurité, une pour les développements internes) et, dans chacune, par équipes disposant de droits en lecture, écriture ou administration sur un ensemble de dépôts. Ce modèle, proche de celui de GitHub, permet d’appliquer le principe du moindre privilège sans gérer les permissions dépôt par dépôt. La version 17 facilite d’ailleurs l’ajout d’un utilisateur dans plusieurs équipes à la fois et propose, en option, un mécanisme d’invitation pour rejoindre une organisation.

# Créer un compte administrateur (mot de passe aléatoire affiché en sortie)
docker exec -u git forgejo forgejo admin user create \
  --admin --username admin-it --email admin@example.org \
  --random-password --must-change-password

# Vérifier l'état de l'instance
docker exec -u git forgejo forgejo doctor check

# Sauvegarde complète (dépôts, base, configuration) au format tar.gz
docker exec -u git forgejo forgejo dump --type tar.gz --file /data/forgejo-dump.tar.gz

# Exemple de workflow Forgejo Actions : .forgejo/workflows/lint.yml
on: [push]
jobs:
  lint:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: echo "Analyse du dépôt"

Forgejo face aux alternatives

Gitea : l’ancêtre commun. Fonctionnellement proche, il est piloté par une société commerciale. Gitea 1.22 est la dernière version permettant une migration transparente vers Forgejo ; au-delà, les deux bases de code divergent.
GitLab CE : beaucoup plus riche (DevSecOps intégré, gestion fine des pipelines), mais nettement plus lourd en ressources et en maintenance. Pertinent pour de grandes équipes de développement, souvent surdimensionné pour une équipe IT ou sécurité.
GitHub / GitHub Enterprise : écosystème et intégrations inégalés, mais SaaS soumis au droit américain ou offre Enterprise Server sous licence propriétaire et payante.
Forgejo : léger, libre (GPL v3+), gouvernance communautaire adossée à une association, compatible avec la syntaxe GitHub Actions. C’est aussi le moteur de Codeberg. Son principal compromis : un écosystème d’intégrations plus restreint et une fédération (ForgeFed, basée sur ActivityPub) encore expérimentale.

Bonnes pratiques de sécurité et d’exploitation

Exposition : publiez l’interface uniquement en HTTPS derrière un reverse proxy, et restreignez le SSH Git aux réseaux nécessaires. Désactivez l’inscription libre (DISABLE_REGISTRATION) sur une instance interne.
Identités : centralisez l’authentification via OIDC ou LDAP, imposez le MFA et privilégiez les jetons d’accès à portée limitée pour les automatisations.
Dépôts : protégez les branches principales, exigez des revues avant fusion et activez la vérification des commits signés (GPG ou SSH).
Runners : isolez-les du reste du SI, n’exécutez pas les workflows de forks non fiables sur des runners ayant accès à des secrets, et limitez les secrets au strict nécessaire.
Sauvegardes : planifiez forgejo dump ou une sauvegarde cohérente du volume de données et de la base, externalisez-la, et testez régulièrement la restauration (un guide dédié a été ajouté avec la version 17).
Mises à jour : suivez les annonces de sécurité, choisissez entre branche LTS et branche courante en connaissance de cause, et lisez les notes de version avant chaque montée majeure (la v17 introduit par exemple des changements cassants sur les liens relatifs et les webhooks d’Actions).

Conclusion

Forgejo coche les cases que recherchent la plupart des équipes IT et sécurité : une forge complète, sobre en ressources, maîtrisée de bout en bout et portée par une gouvernance non lucrative. Pour héberger vos scripts, votre infrastructure as code et vos pipelines CI/CD sans dépendre d’un acteur externe, c’est aujourd’hui l’une des options open source les plus solides. Commencez par une instance de test avec Docker Compose, branchez-la sur votre fournisseur d’identité, puis migrez progressivement vos dépôts.

Partagez cet article !