Forgejo : Hébergez votre Forge Git Moderne (Alternative GitHub/GitLab)

Introduction : Pourquoi héberger sa propre forge Git en 2025-2026 ?

Dans un écosystème de développement logiciel de plus en plus centralisé autour de GitHub (propriété de Microsoft), GitLab.com et Bitbucket (Atlassian), la question de la souveraineté numérique et du contrôle de son code source n'a jamais été aussi pertinente. Les développeurs, les entreprises et les organisations cherchent des alternatives auto-hébergées fiables, légères et fonctionnelles.

C'est dans ce contexte que Forgejo s'impose comme une solution de premier plan. Fork communautaire de Gitea, lui-même issu de Gogs, Forgejo représente l'aboutissement d'une vision : offrir une forge Git complète, légère, performante et gouvernée par sa communauté. Avec des fonctionnalités allant des dépôts Git classiques jusqu'au CI/CD intégré via Forgejo Actions, en passant par la fédération ActivityPub, Forgejo redéfinit ce qu'une forge auto-hébergée peut accomplir.

Architecture en un coup d'œil

Dans cet article exhaustif, nous allons explorer Forgejo sous tous les angles : son histoire, son installation, sa configuration, ses fonctionnalités avancées et sa comparaison avec les alternatives existantes.

Qu'est-ce que Forgejo ?

Origines et historique

Pour comprendre Forgejo, il faut remonter à Gogs, créé en 2014 par Lunny Xiao comme une forge Git auto-hébergée ultra-légère écrite en Go. Gogs était révolutionnaire pour l'époque : un seul binaire, une consommation mémoire minimale et une interface web propre. Cependant, le projet souffrait d'une gouvernance centralisée autour d'un seul mainteneur.

En 2016, une partie de la communauté a forké Gogs pour créer Gitea, avec l'objectif d'avoir une gouvernance plus ouverte et un rythme de développement plus soutenu. Gitea a connu un succès fulgurant et est devenu la référence des forges Git légères.

Fin 2022, la situation a changé lorsque les mainteneurs de Gitea ont créé une entreprise commerciale (Gitea Ltd.) pour monétiser le projet, transférant la propriété du domaine et de la marque à cette entité. Cette décision, prise sans consultation de la communauté, a provoqué un schisme.

En octobre 2022, Forgejo est né comme un soft fork de Gitea, placé sous l'égide de Codeberg e.V., une association à but non lucratif basée en Allemagne. Le nom "Forgejo" vient de l'espéranto et signifie "forge". Depuis, Forgejo est devenu un hard fork à part entière, avec son propre développement, ses propres fonctionnalités et sa propre feuille de route.

Gouvernance communautaire

La différence fondamentale entre Forgejo et Gitea réside dans la gouvernance :

• Forgejo est gouverné par Codeberg e.V., une association à but non lucratif enregistrée en Allemagne. Les décisions sont prises de manière transparente et communautaire. Il n'y a pas d'intérêts commerciaux privés qui influencent la direction du projet.
• Gitea est désormais piloté par Gitea Ltd., une entreprise commerciale. Même si le code reste open-source, les priorités de développement peuvent être influencées par les intérêts commerciaux de l'entreprise.

Cette gouvernance communautaire garantit que Forgejo reste véritablement libre, que les fonctionnalités ne seront pas réservées à une version "Enterprise" payante, et que la communauté a son mot à dire dans l'évolution du projet.

Pourquoi choisir Forgejo plutôt que Gitea ?

Au-delà de la gouvernance, plusieurs raisons techniques et philosophiques motivent le choix de Forgejo :

• Pas de version Enterprise fermée : toutes les fonctionnalités sont disponibles pour tous
• Fédération ActivityPub : Forgejo développe activement la fédération entre instances, permettant l'interaction entre forges comme sur le Fediverse
• Sécurité renforcée : des audits de sécurité réguliers et une politique de sécurité transparente
• Compatibilité : Forgejo reste compatible avec l'écosystème Gitea (thèmes, plugins, API) tout en ajoutant ses propres innovations
• Communauté active : un développement soutenu avec des contributions régulières
• Engagement éthique : pas de tracking, pas de télémétrie, respect total de la vie privée

Installation de Forgejo

Prérequis

Forgejo est remarquablement léger. Voici les ressources minimales recommandées :

• CPU : 1 vCPU (2 recommandés pour une utilisation en équipe)
• RAM : 512 Mo minimum (1 Go recommandé)
• Stockage : 1 Go pour l'application + espace pour vos dépôts
• OS : Linux (Debian, Ubuntu, Fedora, Alpine...), macOS, Windows, FreeBSD
• Base de données : SQLite (petites instances), PostgreSQL (recommandé), MySQL/MariaDB

Comparé à GitLab qui nécessite au minimum 4 Go de RAM et 2 vCPUs, Forgejo est un poids plume qui peut tourner sur un Raspberry Pi.

Installation avec Docker Compose (méthode recommandée)

Docker Compose est la méthode la plus simple et la plus reproductible pour déployer Forgejo. Voici un fichier docker-compose.yml complet et prêt pour la production :

version: "3.8"

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    container_name: forgejo
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      # Configuration de la base de données
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=forgejo-db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=MotDePasseSecurise2025!
      # Configuration du serveur
      - FORGEJO__server__DOMAIN=git.mondomaine.fr
      - FORGEJO__server__SSH_DOMAIN=git.mondomaine.fr
      - FORGEJO__server__ROOT_URL=https://git.mondomaine.fr/
      - FORGEJO__server__SSH_PORT=2222
      - FORGEJO__server__SSH_LISTEN_PORT=22
      - FORGEJO__server__LFS_START_SERVER=true
      # Configuration du service
      - FORGEJO__service__DISABLE_REGISTRATION=false
      - FORGEJO__service__REQUIRE_SIGNIN_VIEW=false
      - FORGEJO__service__DEFAULT_KEEP_EMAIL_PRIVATE=true
      # Configuration du mailer
      - FORGEJO__mailer__ENABLED=true
      - FORGEJO__mailer__PROTOCOL=smtps
      - FORGEJO__mailer__SMTP_ADDR=smtp.mondomaine.fr
      - FORGEJO__mailer__SMTP_PORT=465
      - FORGEJO__mailer__USER=noreply@mondomaine.fr
      - FORGEJO__mailer__PASSWD=MotDePasseSmtp
      - FORGEJO__mailer__FROM=noreply@mondomaine.fr
    volumes:
      - forgejo-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      forgejo-db:
        condition: service_healthy
    networks:
      - forgejo-network

  forgejo-db:
    image: postgres:16-alpine
    container_name: forgejo-db
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=MotDePasseSecurise2025!
      - POSTGRES_DB=forgejo
    volumes:
      - forgejo-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U forgejo"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - forgejo-network

volumes:
  forgejo-data:
    driver: local
  forgejo-db-data:
    driver: local

networks:
  forgejo-network:
    driver: bridge

Lancez l'ensemble avec :

# Créer le répertoire du projet
mkdir -p /opt/forgejo && cd /opt/forgejo

# Créer le fichier docker-compose.yml (collez le contenu ci-dessus)
nano docker-compose.yml

# Lancer les conteneurs
docker compose up -d

# Vérifier que tout fonctionne
docker compose ps
docker compose logs -f forgejo

Forgejo sera accessible sur http://votre-serveur:3000. Lors du premier accès, vous serez redirigé vers l'assistant de configuration initiale.

Installation via binaire

Pour ceux qui préfèrent une installation native sans Docker :

# Télécharger la dernière version de Forgejo
FORGEJO_VERSION="9.0.3"
wget -O forgejo "https://codeberg.org/forgejo/forgejo/releases/download/v${FORGEJO_VERSION}/forgejo-${FORGEJO_VERSION}-linux-amd64"
chmod +x forgejo

# Créer un utilisateur système dédié
sudo adduser --system --shell /bin/bash --gecos 'Forgejo' \
  --group --disabled-password --home /home/forgejo forgejo

# Créer les répertoires nécessaires
sudo mkdir -p /var/lib/forgejo/{custom,data,log}
sudo chown -R forgejo:forgejo /var/lib/forgejo
sudo chmod -R 750 /var/lib/forgejo

# Copier le binaire
sudo cp forgejo /usr/local/bin/forgejo

# Créer le fichier de configuration
sudo mkdir -p /etc/forgejo
sudo chown root:forgejo /etc/forgejo
sudo chmod 770 /etc/forgejo

Créez ensuite un service systemd pour gérer Forgejo :

# Créer le fichier de service systemd
sudo tee /etc/systemd/system/forgejo.service > /dev/null <<'EOF'
[Unit]
Description=Forgejo - A self-hosted Git service
After=syslog.target
After=network.target
After=postgresql.service

[Service]
RestartSec=2s
Type=notify
User=forgejo
Group=forgejo
WorkingDirectory=/var/lib/forgejo/
ExecStart=/usr/local/bin/forgejo web --config /etc/forgejo/app.ini
Restart=always
Environment=USER=forgejo HOME=/home/forgejo FORGEJO_WORK_DIR=/var/lib/forgejo
WatchdogSec=30s

[Install]
WantedBy=multi-user.target
EOF

# Activer et démarrer le service
sudo systemctl daemon-reload
sudo systemctl enable --now forgejo

# Vérifier le statut
sudo systemctl status forgejo

Configuration initiale

Lors du premier lancement, Forgejo vous présente une page de configuration. Les paramètres clés à configurer sont :

• Type de base de données : PostgreSQL pour la production, SQLite pour les petites instances personnelles
• Domaine du serveur : le nom de domaine que vous utiliserez (ex: git.mondomaine.fr)
• URL de base : l'URL complète avec le protocole (ex: https://git.mondomaine.fr/)
• Compte administrateur : créez immédiatement un compte admin

Après la configuration initiale, le fichier app.ini est généré. Vous pouvez le modifier manuellement pour un contrôle plus fin :

# Emplacement du fichier de configuration
# Docker : /data/gitea/conf/app.ini (dans le conteneur)
# Binaire : /etc/forgejo/app.ini

# Exemple de sections importantes dans app.ini
cat /etc/forgejo/app.ini

Fonctionnalités principales de Forgejo

Gestion des dépôts Git

Forgejo offre une gestion complète des dépôts Git avec une interface web élégante et intuitive :

• Dépôts publics et privés : contrôle total de la visibilité
• Branches protégées : règles de protection (reviews obligatoires, CI requis, restrictions de push)
• Git LFS : support natif de Large File Storage pour les fichiers volumineux
• Mirroring : miroirs push et pull depuis/vers GitHub, GitLab ou d'autres instances
• Éditeur web : modification de fichiers directement depuis l'interface avec prévisualisation Markdown
• Recherche de code : indexation et recherche full-text dans le code source (via Bleve ou Elasticsearch)
• Commits signés : vérification et affichage des signatures GPG/SSH
• Tags et releases : gestion des versions avec assets téléchargeables
• Templates de dépôt : créer des dépôts modèles réutilisables

Issues et suivi de bugs

Le système d'issues de Forgejo est complet et rivalise avec celui de GitHub :

• Labels : étiquettes colorées personnalisables avec support des labels de scope (ex: priorité/haute)
• Milestones : jalons avec suivi de progression
• Assignation : assignation multiple, auto-assignation
• Templates d'issues : formulaires YAML pour structurer les rapports de bugs et demandes de fonctionnalités
• Réactions : émojis sur les commentaires
• Références croisées : liens automatiques entre issues, PRs et commits
• Verrouillage : possibilité de verrouiller les discussions
• Dépendances : marquer des issues comme bloquées par d'autres

Pull Requests

Les Pull Requests (ou Merge Requests) dans Forgejo supportent :

• Reviews de code : commentaires en ligne, approbation, demande de modifications
• Merge strategies : merge commit, rebase, squash, fast-forward
• Auto-merge : fusion automatique quand toutes les conditions sont remplies
• Draft PRs : marquer une PR comme brouillon (Work in Progress)
• Vérifications de statut : intégration avec le CI/CD pour bloquer le merge si les tests échouent
• CODEOWNERS : assignation automatique de reviewers basée sur les fichiers modifiés

Wiki intégré

Chaque dépôt peut activer un wiki intégré. Le wiki est lui-même un dépôt Git, ce qui signifie que vous pouvez le cloner, le modifier localement et le pousser. Il supporte le Markdown avec des extensions comme les diagrammes Mermaid, les formules mathématiques LaTeX et les tableaux.

Projects (tableaux Kanban)

Forgejo inclut des tableaux de projet de type Kanban directement intégrés. Vous pouvez créer des colonnes personnalisées, y glisser-déposer des issues et des PRs, et suivre l'avancement visuel de vos projets. C'est une alternative légère à Trello ou Jira pour la gestion de projet agile.

Packages Registry

Forgejo intègre un registre de paquets universel supportant de nombreux formats :

• Container (images Docker OCI)
• npm (JavaScript/Node.js)
• PyPI (Python)
• Maven (Java)
• NuGet (.NET)
• Cargo (Rust)
• Composer (PHP)
• Helm (Kubernetes Charts)
• Generic (tout type de fichier)

Cette fonctionnalité permet de centraliser votre code et vos artefacts de build au même endroit, sans avoir besoin d'un registre externe.

# Exemple : pousser une image Docker vers le registre Forgejo
docker login git.mondomaine.fr
docker tag mon-app:latest git.mondomaine.fr/monuser/mon-app:1.0.0
docker push git.mondomaine.fr/monuser/mon-app:1.0.0

# Exemple : publier un package npm
npm config set registry https://git.mondomaine.fr/api/packages/monuser/npm/
npm publish

Forgejo Actions : le CI/CD intégré

Présentation

Forgejo Actions est la fonctionnalité la plus attendue et la plus puissante de Forgejo. Il s'agit d'un système de CI/CD intégré directement dans la forge, compatible avec la syntaxe des GitHub Actions. Cela signifie que vous pouvez réutiliser vos workflows GitHub existants avec peu ou pas de modifications.

Forgejo Actions utilise des runners qui exécutent les jobs. Le runner officiel est Forgejo Runner, basé sur act_runner (lui-même inspiré de nektos/act).

Activer Forgejo Actions

Pour activer les Actions dans votre instance Forgejo, ajoutez dans votre fichier app.ini :

# Dans le fichier app.ini ou via variables d'environnement Docker
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org

Ou via les variables d'environnement Docker :

# Dans docker-compose.yml, section environment de forgejo
- FORGEJO__actions__ENABLED=true
- FORGEJO__actions__DEFAULT_ACTIONS_URL=https://code.forgejo.org

Déployer un Forgejo Runner

Le runner est le composant qui exécute les workflows. Voici comment le déployer avec Docker :

# 1. Obtenir le token d'enregistrement depuis l'interface admin
# Administration du site > Runners > Créer un nouveau runner

# 2. Enregistrer le runner
docker run --rm -it \
  -v /opt/forgejo-runner/data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  code.forgejo.org/forgejo/runner:6 \
  forgejo-runner register \
  --instance https://git.mondomaine.fr \
  --token VOTRE_TOKEN_ICI \
  --name runner-01 \
  --labels docker:docker://node:20-bookworm,ubuntu-latest:docker://ubuntu:24.04

# 3. Lancer le runner en tant que service
docker run -d \
  --name forgejo-runner \
  --restart always \
  -v /opt/forgejo-runner/data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  code.forgejo.org/forgejo/runner:6 \
  forgejo-runner daemon

Exemple de workflow Forgejo Actions

Voici un exemple complet de workflow CI/CD pour une application Node.js. Créez le fichier .forgejo/workflows/ci.yml à la racine de votre dépôt :

# .forgejo/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'
  REGISTRY: git.mondomaine.fr
  IMAGE_NAME: ${{ github.repository }}

jobs:
  lint-and-test:
    name: Lint & Tests
    runs-on: docker
    container:
      image: node:20-bookworm
    steps:
      - name: Checkout du code
        uses: https://code.forgejo.org/actions/checkout@v4

      - name: Cache des dépendances npm
        uses: https://code.forgejo.org/actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

      - name: Installation des dépendances
        run: npm ci

      - name: Linting
        run: npm run lint

      - name: Tests unitaires
        run: npm run test -- --coverage

      - name: Tests d'intégration
        run: npm run test:integration

  security-scan:
    name: Audit de sécurité
    runs-on: docker
    container:
      image: node:20-bookworm
    steps:
      - name: Checkout du code
        uses: https://code.forgejo.org/actions/checkout@v4

      - name: Audit des dépendances
        run: npm audit --audit-level=high

  build-and-push:
    name: Build & Push Docker Image
    runs-on: docker
    needs: [lint-and-test, security-scan]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - name: Checkout du code
        uses: https://code.forgejo.org/actions/checkout@v4

      - name: Login au registre Forgejo
        uses: https://code.forgejo.org/actions/docker-login@v1
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.REGISTRY_TOKEN }}

      - name: Build et push de l'image
        run: |
          docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest .
          docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} .
          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

  deploy:
    name: Déploiement en production
    runs-on: docker
    needs: [build-and-push]
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Déploiement via SSH
        run: |
          apt-get update && apt-get install -y openssh-client
          mkdir -p ~/.ssh
          echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh -o StrictHostKeyChecking=no deploy@production.mondomaine.fr \
            "cd /opt/mon-app && docker compose pull && docker compose up -d"

Ce workflow illustre un pipeline CI/CD complet : lint, tests, audit de sécurité, build d'image Docker, push vers le registre intégré de Forgejo, et déploiement automatique en production.

Différences avec GitHub Actions

Bien que Forgejo Actions soit compatible avec la syntaxe GitHub Actions, quelques différences existent :

• Les actions tierces doivent être référencées avec leur URL complète (ex: uses: https://code.forgejo.org/actions/checkout@v4 au lieu de uses: actions/checkout@v4)
• Le répertoire des workflows est .forgejo/workflows/ (mais .github/workflows/ est aussi supporté pour la compatibilité)
• Les runners utilisent Docker par défaut, pas des VMs comme GitHub-hosted runners
• Les actions du marketplace GitHub ne sont pas toutes disponibles, mais Forgejo maintient un catalogue d'actions compatibles sur code.forgejo.org

Migration depuis GitHub, GitLab ou Gitea

Migration depuis GitHub

Forgejo intègre un outil de migration puissant accessible directement depuis l'interface web :

1. Cliquez sur "+" puis "Nouvelle migration"
2. Sélectionnez GitHub comme source
3. Entrez l'URL du dépôt (ex: https://github.com/user/repo)
4. Fournissez un Personal Access Token GitHub pour accéder aux dépôts privés et importer les métadonnées
5. Choisissez ce que vous souhaitez migrer : issues, labels, milestones, releases, pull requests, wiki

Vous pouvez aussi migrer en masse via l'API REST :

# Migration d'un dépôt GitHub via l'API Forgejo
curl -X POST "https://git.mondomaine.fr/api/v1/repos/migrate" \
  -H "Authorization: token VOTRE_TOKEN_FORGEJO" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://github.com/user/repo.git",
    "auth_token": "VOTRE_TOKEN_GITHUB",
    "repo_name": "repo",
    "repo_owner": "monorg",
    "service": "github",
    "mirror": false,
    "issues": true,
    "labels": true,
    "milestones": true,
    "releases": true,
    "pull_requests": true,
    "wiki": true
  }'

Migration depuis GitLab

Le processus est similaire. Forgejo supporte la migration depuis GitLab (y compris les instances auto-hébergées) en important les dépôts, issues, labels, milestones et pull requests. Notez que le CI/CD GitLab (.gitlab-ci.yml) devra être converti manuellement en workflows Forgejo Actions.

Migration depuis Gitea

La migration depuis Gitea est la plus simple puisque Forgejo est un fork de Gitea. Deux approches sont possibles :

• Migration en place : remplacez simplement le binaire Gitea par celui de Forgejo. La base de données et les données sont compatibles. Forgejo effectuera les migrations de schéma nécessaires au premier démarrage.
• Migration via l'API : utilisez l'outil de migration intégré comme pour GitHub/GitLab.

# Migration en place depuis Gitea vers Forgejo (binaire)
sudo systemctl stop gitea

# Sauvegarder d'abord !
sudo cp -r /var/lib/gitea /var/lib/gitea.backup
sudo cp /etc/gitea/app.ini /etc/gitea/app.ini.backup

# Remplacer le binaire
sudo wget -O /usr/local/bin/forgejo \
  "https://codeberg.org/forgejo/forgejo/releases/download/v9.0.3/forgejo-9.0.3-linux-amd64"
sudo chmod +x /usr/local/bin/forgejo

# Mettre à jour le service systemd pour pointer vers forgejo
sudo sed -i 's|/usr/local/bin/gitea|/usr/local/bin/forgejo|g' /etc/systemd/system/gitea.service
sudo systemctl daemon-reload
sudo systemctl start gitea  # Le service peut garder le même nom

Webhooks et intégrations

Webhooks

Forgejo supporte les webhooks pour déclencher des actions externes lors d'événements sur vos dépôts. Les formats supportés incluent :

• Forgejo (format natif)
• Gitea (compatible)
• Slack
• Discord
• Microsoft Teams
• Mattermost
• Feishu/Lark
• Telegram
• DingTalk
• Matrix
• Personnalisé (webhook générique HTTP)

Les événements déclencheurs disponibles sont nombreux : push, création de branche/tag, pull request (ouverture, mise à jour, merge), issues, commentaires, releases, fork, etc.

# Créer un webhook via l'API
curl -X POST "https://git.mondomaine.fr/api/v1/repos/monuser/monrepo/hooks" \
  -H "Authorization: token VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slack",
    "active": true,
    "config": {
      "url": "https://hooks.slack.com/services/XXXX/YYYY/ZZZZ",
      "content_type": "json"
    },
    "events": ["push", "pull_request", "issues"]
  }'

OAuth2 et OIDC

Forgejo peut à la fois consommer et fournir des services d'authentification OAuth2/OIDC :

En tant que client OAuth2 (connexion via un fournisseur externe) :

• GitHub, GitLab, Gitea, Forgejo
• Google, Microsoft/Azure AD
• OpenID Connect générique (compatible Authentik, Keycloak, etc.)
• LDAP/Active Directory

En tant que fournisseur OAuth2 (permettre à d'autres applications de se connecter via Forgejo) :

• Forgejo peut servir de fournisseur d'identité OAuth2 pour vos autres applications
• Utile pour centraliser l'authentification de votre homelab autour de votre forge

# Configurer une source d'authentification OIDC via la CLI
forgejo admin auth add-oauth \
  --name "Authentik" \
  --provider openidConnect \
  --key "forgejo-client-id" \
  --secret "forgejo-client-secret" \
  --auto-discover-url "https://auth.mondomaine.fr/application/o/forgejo/.well-known/openid-configuration" \
  --group-claim-name "groups" \
  --admin-group "forgejo-admins"

Fédération ActivityPub : l'avenir des forges

Qu'est-ce que la fédération ?

La fédération ActivityPub est l'une des fonctionnalités les plus innovantes et distinctives de Forgejo. Inspirée du Fediverse (Mastodon, Lemmy, PeerTube...), la fédération permet à différentes instances Forgejo de communiquer entre elles.

Concrètement, cela signifie qu'un utilisateur sur l'instance forge-a.org pourrait :

• Suivre un utilisateur ou un dépôt sur forge-b.org
• Star (mettre en favori) un dépôt distant
• Forker un dépôt entre instances
• Ouvrir des issues et des pull requests inter-instances
• Recevoir des notifications d'activité depuis d'autres forges

État actuel de la fédération

En 2025-2026, la fédération Forgejo est en développement actif. Les premières fonctionnalités sont disponibles en mode expérimental :

• Profils fédérés : les profils utilisateurs sont exposés via ActivityPub
• Suivi d'utilisateurs : on peut suivre des utilisateurs sur d'autres instances
• Star fédéré : mettre en favori un dépôt distant
• Recherche fédérée : trouver des dépôts et des utilisateurs sur d'autres instances

Les fonctionnalités plus avancées comme les issues et PRs inter-instances sont en cours de développement dans le cadre du projet ForgeFed, une spécification ouverte pour la fédération des forges logicielles.

# Activer la fédération (expérimentale) dans app.ini
[federation]
ENABLED = true

# Ou via variable d'environnement Docker
# FORGEJO__federation__ENABLED=true

La fédération représente un changement de paradigme : au lieu d'un GitHub centralisé, on tend vers un réseau décentralisé de forges interconnectées, où chaque organisation gère son instance tout en pouvant collaborer avec le reste de l'écosystème.

API REST compatible GitHub

Forgejo expose une API REST complète largement compatible avec l'API GitHub. Cela signifie que de nombreux outils et scripts conçus pour GitHub fonctionnent avec Forgejo moyennant un simple changement d'URL de base.

L'API couvre :

• Gestion des dépôts (CRUD, forks, stars, watchers)
• Issues et commentaires
• Pull requests et reviews
• Utilisateurs et organisations
• Teams et permissions
• Webhooks
• Releases et tags
• Packages
• Administration (pour les admins d'instance)

La documentation interactive Swagger est disponible à https://votre-instance/api/swagger.

# Exemples d'utilisation de l'API REST

# Lister vos dépôts
curl -s "https://git.mondomaine.fr/api/v1/user/repos" \
  -H "Authorization: token VOTRE_TOKEN" | jq '.[].full_name'

# Créer un nouveau dépôt
curl -X POST "https://git.mondomaine.fr/api/v1/user/repos" \
  -H "Authorization: token VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nouveau-projet",
    "description": "Mon nouveau projet",
    "private": false,
    "auto_init": true,
    "default_branch": "main",
    "license": "MIT"
  }'

# Créer une issue
curl -X POST "https://git.mondomaine.fr/api/v1/repos/monuser/monrepo/issues" \
  -H "Authorization: token VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bug: problème d'\''affichage",
    "body": "Description détaillée du bug...",
    "labels": [1, 3]
  }'

# Rechercher des dépôts
curl -s "https://git.mondomaine.fr/api/v1/repos/search?q=docker&limit=10" \
  -H "Authorization: token VOTRE_TOKEN" | jq '.[].full_name'

Personnalisation et thèmes

Forgejo est hautement personnalisable :

• Thèmes : thèmes clair et sombre intégrés, possibilité d'ajouter des thèmes personnalisés CSS
• Logo et branding : remplacez le logo, le favicon et le nom de l'application
• Templates : personnalisez les templates Go pour modifier l'interface
• Page d'accueil : personnalisez la page d'accueil de votre instance
• Footer : ajoutez des liens personnalisés dans le pied de page

# Structure des fichiers de personnalisation
# Dans le répertoire custom de Forgejo
/data/gitea/custom/
├── public/
│   ├── assets/
│   │   └── img/
│   │       ├── logo.svg          # Logo personnalisé
│   │       └── favicon.svg       # Favicon personnalisé
│   └── css/
│       └── theme-custom.css      # Thème CSS personnalisé
├── templates/
│   ├── home.tmpl                 # Page d'accueil personnalisée
│   └── custom/
│       ├── header.tmpl           # En-tête personnalisé
│       └── footer.tmpl           # Pied de page personnalisé
└── options/
    └── locale/
        └── locale_fr-FR.ini      # Traductions personnalisées

Comparaison avec les alternatives

Pour vous aider à faire votre choix, voici une comparaison détaillée de Forgejo avec ses principales alternatives :

Quand choisir Forgejo ?

• Vous valorisez la gouvernance communautaire et le logiciel véritablement libre
• Vous avez des ressources limitées (VPS modeste, Raspberry Pi, homelab)
• Vous voulez un CI/CD intégré sans installer Jenkins, Drone ou autre outil externe
• La fédération vous intéresse pour une collaboration inter-organisations
• Vous migrez depuis GitHub et voulez conserver une expérience similaire
• Vous ne voulez pas de version "Enterprise" avec des fonctionnalités verrouillées

Quand choisir GitLab plutôt ?

• Vous avez besoin de fonctionnalités très avancées : DORA metrics, security scanning intégré, DevSecOps complet, compliance, Kubernetes agent natif
• Vous avez une grande équipe (50+ développeurs) avec des besoins de gouvernance complexes
• Vous avez les ressources serveur pour faire tourner GitLab (minimum 8 Go de RAM recommandés)

Bonnes pratiques de production

Sécurité

• Désactivez l'inscription publique si votre instance est privée : DISABLE_REGISTRATION = true
• Activez l'authentification à deux facteurs (2FA) et encouragez son usage
• Mettez à jour régulièrement : suivez les releases de sécurité sur Codeberg
• Utilisez HTTPS systématiquement (via un reverse proxy comme Nginx, Caddy ou Traefik)
• Limitez l'accès SSH : n'exposez le port SSH que si nécessaire
• Configurez des limites de rate pour l'API

Sauvegardes

# Script de sauvegarde complet pour Forgejo
#!/bin/bash
BACKUP_DIR="/opt/backups/forgejo"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Sauvegarde de la base de données PostgreSQL
docker exec forgejo-db pg_dump -U forgejo forgejo | \
  gzip > "$BACKUP_DIR/db_${DATE}.sql.gz"

# Sauvegarde des données Forgejo (repos, avatars, attachments, LFS)
docker run --rm \
  -v forgejo-data:/data:ro \
  -v "$BACKUP_DIR":/backup \
  alpine tar czf "/backup/data_${DATE}.tar.gz" /data

# Nettoyage des sauvegardes de plus de 30 jours
find "$BACKUP_DIR" -type f -mtime +30 -delete

echo "Sauvegarde terminée : $BACKUP_DIR/*_${DATE}.*"

Reverse proxy avec Nginx

# Configuration Nginx pour Forgejo
server {
    listen 443 ssl http2;
    server_name git.mondomaine.fr;

    ssl_certificate /etc/letsencrypt/live/git.mondomaine.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.mondomaine.fr/privkey.pem;

    client_max_body_size 512M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

server {
    listen 80;
    server_name git.mondomaine.fr;
    return 301 https://$server_name$request_uri;
}

Monitoring

Forgejo expose des métriques Prometheus sur le endpoint /metrics (à activer dans la configuration). Vous pouvez ainsi surveiller votre instance avec Prometheus + Grafana :

# Activer les métriques dans app.ini
[metrics]
ENABLED = true
TOKEN = votre-token-metrics-secret

# Ou via variable d'environnement Docker
# FORGEJO__metrics__ENABLED=true
# FORGEJO__metrics__TOKEN=votre-token-metrics-secret

Cas d'usage concrets

Homelab et projets personnels

Forgejo est idéal pour un homelab. Avec sa faible consommation de ressources, il peut tourner sur un Raspberry Pi 4 et servir de forge personnelle pour tous vos projets. Combiné avec Forgejo Actions, vous avez un pipeline CI/CD complet sans aucun service cloud.

PME et startups

Pour une petite équipe de 5 à 20 développeurs, Forgejo offre toutes les fonctionnalités nécessaires sans la complexité et le coût de GitLab ou GitHub Enterprise. Un simple VPS à 10 euros par mois suffit pour héberger une instance performante.

Organisations et associations

La gouvernance communautaire et l'absence de version Enterprise payante font de Forgejo un choix naturel pour les associations, les ONG et les organisations qui valorisent le logiciel libre. L'instance Codeberg.org, qui héberge Forgejo lui-même, en est le meilleur exemple.

Éducation

Les universités et écoles peuvent déployer Forgejo pour enseigner Git et le développement collaboratif. Les étudiants peuvent créer leurs comptes, soumettre leurs travaux via des pull requests, et les enseignants peuvent reviewer le code comme dans un workflow professionnel.

Conclusion

Forgejo représente une évolution majeure dans l'écosystème des forges Git auto-hébergées. En combinant la légèreté héritée de Gitea/Gogs, une gouvernance véritablement communautaire sous Codeberg e.V., un CI/CD intégré compatible GitHub Actions, un registre de paquets multi-format et la promesse de la fédération ActivityPub, Forgejo se positionne comme la solution de référence pour quiconque souhaite héberger sa propre forge en 2025-2026.

Que vous soyez un développeur individuel avec un Raspberry Pi, une startup cherchant à réduire ses coûts, ou une organisation soucieuse de sa souveraineté numérique, Forgejo mérite votre attention. Son installation prend moins de 10 minutes avec Docker Compose, et la migration depuis GitHub, GitLab ou Gitea est facilitée par des outils intégrés.

Le futur de Forgejo est prometteur : la fédération ActivityPub, une fois mature, pourrait transformer radicalement la manière dont nous collaborons sur du code open-source, en passant d'un modèle centralisé à un réseau décentralisé de forges interconnectées. C'est une vision ambitieuse, et Forgejo est en train de la concrétiser.

Ressources utiles :
Site officiel : forgejo.org
Code source : codeberg.org/forgejo/forgejo
Documentation : forgejo.org/docs
Instance de démonstration : Codeberg.org (propulsé par Forgejo)
Forum communautaire : forum.forgejo.org