Migrer ses repos depuis GitHub vers Forgejo self-hosted est une opération qui peut sembler intimidante mais qui se fait en réalité en quelques heures grâce à l’import natif Forgejo qui copie code, issues, PR, wiki, releases. Voici le guide pratique 2026 pour migrer proprement, sans perdre l’historique ni la collaboration en cours.

Voir notre guide Forgejo.

Ce que la migration préserve

Code source complet avec tout l’historique Git
Toutes les branches
Tags et releases (avec assets binaires)
Issues (avec auteurs, labels, assignés, milestones)
Pull requests (avec reviews)
Wiki
Comments des issues et PR

Ce qui ne migre pas automatiquement

GitHub Actions workflows (à adapter manuellement, mais 90 % compatible)
Secrets repo (à recréer)
Webhooks (à reconfigurer)
Settings spécifiques GitHub (Pages, Discussions, Sponsors)
Forks externes (les forks deviennent des repos indépendants)

Étape 1 — Préparer côté GitHub

Aller sur github.com/settings/tokens
Generate new token (classic) → cocher repo, read:org, read:user
Copier le token (commence par ghp_)

Étape 2 — Importer dans Forgejo

Forgejo → « + » → « New Migration » (ou Repos → New Repository → Migrate)
Service : « GitHub »
Clone Address : https://github.com/votre-org/votre-repo
Authorization (token) : votre ghp_xxx
Owner : votre user ou organisation Forgejo
Repository name : nom à donner
Cocher : Issues, Pull Requests, Releases, Wiki, Labels, Milestones
Visibility : Private (recommandé pour démarrer)
Submit

L’import prend quelques minutes à quelques heures selon la taille du repo et le nombre d’issues/PR. Forgejo affiche la progression.

Étape 3 — Mirror push vers GitHub (optionnel)

Si vous voulez maintenir GitHub comme miroir public pendant la transition :

Repo Forgejo → Settings → Advanced → Push Mirror
URL : https://github.com/votre-org/votre-repo.git
Username + Token GitHub
Sync Interval : 8h ou à la demande

Forgejo poussera désormais automatiquement chaque commit vers GitHub.

Étape 4 — Migrer les workflows GitHub Actions

Les workflows YAML dans .github/workflows/ doivent être déplacés dans .forgejo/workflows/ ou .gitea/workflows/. La syntaxe est compatible à 90 %. Voir notre guide Forgejo Actions.

# Renommer le dossier
git mv .github/workflows .forgejo/workflows

# Vérifier les références aux secrets et variables, ajuster si besoin
# Test : push, vérifier que le workflow s'exécute

Étape 5 — Mettre à jour les remotes des laptops

# Sur chaque laptop dev
git remote set-url origin git@git.exemple.sn:user/repo.git
git remote -v
# vérifier l'URL change

Étape 6 — Recréer secrets et webhooks

Repo Forgejo → Settings → Secrets → recréer tous les secrets nécessaires
Repo Forgejo → Settings → Webhooks → recréer si vous aviez des intégrations externes (Slack, Discord, Sentry, Linear)
Recréer les Deploy Keys si nécessaire

Étape 7 — Migrer les contributeurs

Les commits gardent leur signature email d’origine. Pour que les contributeurs voient leurs commits liés à leur compte Forgejo, ils doivent ajouter dans leur profil l’email utilisé sur GitHub. Pas de migration automatique des comptes utilisateurs.

Étape 8 — Période de double-écriture

Pour minimiser les ruptures, gardez les deux remotes pendant 2-4 semaines :

# Configurer plusieurs remotes
git remote add forgejo git@git.exemple.sn:user/repo.git
git remote add github git@github.com:org/repo.git

# Push aux deux
git push forgejo main
git push github main

# Ou via mirror push automatique côté Forgejo (étape 3)

Étape 9 — Couper GitHub définitivement

S’assurer que tout l’historique est bien sur Forgejo
S’assurer que tous les contributeurs ont basculé
Archiver le repo GitHub (Settings → Archive) plutôt que supprimer
Supprimer les remotes github des laptops

Adaptation Afrique de l’Ouest

Pour une PME ouest-africaine de 5-10 développeurs, la migration GitHub → Forgejo est typiquement faite sur un weekend : import vendredi soir, validation samedi, communication équipe + bascule remotes lundi. Économie immédiate de 40-200 USD/mois selon le plan GitHub précédent.

Erreurs fréquentes

Erreur	Cause	Solution
Import très lent	Beaucoup d’issues	Patience, ou import code+wiki seulement puis issues séparément
Mirror push échoue	Token GitHub expiré ou portée	Régénérer token avec scope repo
Workflows GitHub Actions cassent	Actions tierces incompatibles	Adapter manuellement, voir guide Forgejo Actions
Issues sans assignee	User GitHub pas trouvé chez Forgejo	Créer compte avant import, ou ajuster post-migration

Etape 1 : evaluer ce que vous voulez vraiment migrer

Forgejo est un fork communautaire de Gitea ne en 2022 et porte par le projet Codeberg. En 2026, il a depasse la version 9 et propose un compatibilite poussee avec l’API GitHub : code, issues, pull requests, releases, wiki, et meme Forgejo Actions qui execute les memes workflows YAML que GitHub Actions. Avant de migrer, listez precisement ce qui doit traverser :

Code source des branches (toujours indispensable).
Historique des issues et leurs commentaires.
Pull requests ouvertes et closes (avec leurs reviews).
Releases et tags signes.
Workflows Actions et secrets utilises par les CI.

Ce diagnostic conditionne la strategie : un simple git clone --mirror suffit pour le code, mais issues et PR demandent l’API GitHub avec un token a portee suffisante.

Etape 2 : preparer un VPS Forgejo avec Docker Compose

Le plus rapide est de deployer Forgejo via Docker. Sur un VPS situe a Paris ou Frankfurt (latence raisonnable depuis Dakar, Lome ou Cotonou), creez le repertoire et le fichier compose.

mkdir -p /opt/forgejo && cd /opt/forgejo
cat > docker-compose.yml <<'EOF'
services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./data:/data
    ports:
      - "3000:3000"
      - "2222:22"
EOF
docker compose up -d
docker compose ps

La sortie doit afficher l’etat running avec un health check vert apres 30 secondes. Ouvrez ensuite http://IP_VPS:3000 et terminez l’assistant initial : nom du site, base de donnees integree SQLite (suffisante jusqu’a 50 utilisateurs), compte administrateur.

Etape 3 : creer un token GitHub avec les bonnes portees

Pour migrer issues et PR, Forgejo a besoin d’un token GitHub disposant des scopes repo et read:org. Generez-le sur github.com/settings/tokens en mode classic, copiez-le immediatement (il n’est plus jamais affiche apres).

Conservez ce token dans un gestionnaire de mots de passe (Bitwarden ou KeePassXC en local). Ne jamais le coller dans un Slack public ni dans un email non chiffre : un token avec le scope repo permet de lire et ecrire sur tous vos depots prives.

Etape 4 : lancer la migration via l’interface Forgejo

Connectez-vous a votre Forgejo, cliquez sur le plus en haut a droite puis Nouvelle migration. Choisissez GitHub dans la liste. Renseignez l’URL du depot source, votre login et le token genere.

Cochez les cases : Wiki, Issues, Pull Requests, Releases, Labels, Milestones. Lancez la migration. Pour un depot moyen (500 commits, 200 issues, 50 PR), comptez 3 a 8 minutes selon la latence reseau. La page se rafraichit automatiquement et affiche Migration terminee a la fin.

Etape 5 : verifier l’integrite du code et des branches

Avant de declarer la migration reussie, comparez les empreintes des branches entre GitHub et Forgejo. Une difference signale un probleme (souvent un sous-module manquant ou un LFS non configure).

git clone --mirror git@github.com:org/depot.git /tmp/source
git clone --mirror https://forgejo.exemple.sn/org/depot.git /tmp/cible
cd /tmp/source && git rev-parse HEAD > /tmp/h1.txt
cd /tmp/cible && git rev-parse HEAD > /tmp/h2.txt
diff /tmp/h1.txt /tmp/h2.txt
# Sortie attendue : aucune difference

Si diff retourne du texte, c’est que la branche par defaut a divergé. Reverifiez quel depot fait foi et synchronisez avec un git push --mirror depuis la source vers la cible.

Etape 6 : migrer les Git LFS si vous en utilisez

Les fichiers LFS (binaires lourds, images haute resolution, datasets) ne sont pas inclus dans la migration standard. Forgejo supporte LFS depuis longtemps mais il faut pousser explicitement les objets.

cd /chemin/vers/depot-local
git lfs fetch --all origin
git remote add forgejo https://forgejo.exemple.sn/org/depot.git
git lfs push --all forgejo
# Sortie attendue : Uploading X objects (Y MB)

Verifiez ensuite dans l’interface Forgejo que la taille du depot reflete bien les objets LFS. Si elle reste a 50 ko alors que vous attendiez 500 Mo, c’est que le push LFS a echoue silencieusement (token sans scope ou quota disque atteint sur le VPS).

Etape 7 : convertir les workflows GitHub Actions vers Forgejo Actions

Forgejo Actions reutilise la syntaxe YAML de GitHub Actions, mais certaines actions du marketplace ne sont pas disponibles. Listez vos workflows et identifiez les actions externes utilisees.

cat .forgejo/workflows/ci.yml
# Exemple minimal
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: npm install && npm test

Deplacez le repertoire .github/workflows vers .forgejo/workflows puis poussez. Verifiez que le runner repond bien a un push de test : la page Actions du depot doit afficher un job en cours puis vert.

Etape 8 : enregistrer un runner Forgejo Actions sur un VPS

Sans runner, aucun workflow ne s’execute. Installez le binaire forgejo-runner sur un second VPS ou en container sur la meme machine.

wget -O forgejo-runner \
  https://code.forgejo.org/forgejo/runner/releases/download/v6.0.0/forgejo-runner-6.0.0-linux-amd64
chmod +x forgejo-runner
./forgejo-runner register --instance https://forgejo.exemple.sn --token RUNNER_TOKEN
./forgejo-runner daemon
# Sortie attendue : runner registered, polling for jobs

Le token de runner s’obtient dans Site Administration > Actions > Runners. Lancez le daemon dans systemd pour qu’il survive aux redemarrages, puis surveillez avec journalctl -u forgejo-runner -f.

Etape 9 : transferer les secrets et variables d’environnement

Les secrets GitHub Actions ne sont pas exportables : ils sont chiffres a sens unique. Vous devez les recreer manuellement dans Forgejo. Ouvrez Parametres > Actions > Secrets et ajoutez chaque cle.

Pour un projet qui paye via Wave ou Mixx by Yas, les secrets typiques sont : WAVE_API_KEY, DB_URL, SMTP_PASSWORD. Une regle de base : un secret par environnement (dev, staging, prod), jamais partage. Verifiez ensuite qu’un workflow de test peut lire le secret avec echo ${{ secrets.WAVE_API_KEY }} | wc -c.

Etape 10 : rediriger les anciennes URLs GitHub vers Forgejo

Si votre depot etait reference dans des articles de blog, des README de partenaires ou des pipelines tiers, les liens GitHub continuent de fonctionner mais pointent vers l’ancien code. Deux strategies : conserver GitHub en mirror lecture seule, ou archiver le depot avec un README qui pointe vers Forgejo.

# Au sommet du README GitHub
> Ce depot est archive. Le developpement continue sur :
> https://forgejo.exemple.sn/org/depot

Cliquez ensuite sur Settings > Archive this repository sur GitHub. Cela bloque les nouvelles issues et PR sans casser les liens existants. Les visiteurs comprennent immediatement ou aller.

Etape 11 : configurer les sauvegardes Forgejo automatisees

Une migration sans plan de sauvegarde est une bombe a retardement. Forgejo fournit une commande dump qui produit une archive complete (base, configurations, depots, attachments).

docker compose exec -u 1000:1000 forgejo \
  forgejo dump -c /data/gitea/conf/app.ini -t /tmp
docker compose cp forgejo:/tmp/forgejo-dump-XXX.zip ./backups/
rclone copy ./backups/ b2:itsc-backup/forgejo/
# Sortie attendue : archive zip de plusieurs centaines de Mo

Programmez ce script en cron quotidien et conservez 7 jours roulants plus une sauvegarde mensuelle pendant 12 mois. Tester regulierement la restauration sur un VPS de staging est ce qui distingue une vraie sauvegarde d’une illusion.

Etape 12 : former l’equipe et documenter les workflows

La derniere etape, souvent negligee, est humaine. Vos developpeurs ont des annees de reflexes GitHub : commande gh pr create, integrations VS Code, notifications email. Forgejo offre une CLI compatible (tea) et la majorite des extensions VS Code Git fonctionnent sans changement.

Organisez un atelier d’une heure pour montrer : creer une issue, ouvrir une PR, lancer un workflow, configurer le client SSH avec la nouvelle URL. Documentez tout dans un wiki interne. Pour relier le tout a un VPN d’entreprise, voyez notre guide Headscale, et pour optimiser un frontend qui consomme l’API Forgejo, consultez le tutoriel Astro Server Islands.

Etape 13 : auditer la consommation disque apres 30 jours

Apres un mois d’utilisation, le repertoire /opt/forgejo/data peut grossir vite : objets git, attachments d’issues, artefacts d’Actions. Mesurez avant que le disque ne sature.

du -sh /opt/forgejo/data/*
# Sortie attendue : repos 8G, attachments 1.2G, actions 4G
docker compose exec forgejo forgejo doctor check --all
# Sortie attendue : tous les checks OK

Si actions depasse 10 Go, configurez une retention plus courte dans app.ini (par exemple ARTIFACT_RETENTION_DAYS = 14). Les anciens artefacts seront purges automatiquement, ce qui evite la coupure du jour ou le disque sature.

Etape 14 : monitorer la disponibilite avec Uptime Kuma

Pour eviter qu’une PME a Dakar decouvre l’indisponibilite de son git interne en arrivant au bureau, ajoutez Uptime Kuma sur un VPS distinct. Configurez un monitor HTTP toutes les 60 secondes sur l’URL Forgejo.

docker run -d --restart=always -p 3001:3001 \
  -v uptime-kuma:/app/data --name uptime-kuma \
  louislam/uptime-kuma:1
# Acceder a http://IP:3001 et ajouter https://forgejo.exemple.sn

Branchez la notification sur un canal Telegram ou un webhook Slack. Le seuil 3 echecs consecutifs evite les fausses alertes liees a une coupure reseau de quelques secondes, tres courantes sur les liens vers l’Afrique de l’Ouest.

Migrer GitHub vers Forgejo : tutoriel 2026 (code, issues, PR, Actions)

Ce que la migration préserve

Ce qui ne migre pas automatiquement

Étape 1 — Préparer côté GitHub

Étape 2 — Importer dans Forgejo

Étape 3 — Mirror push vers GitHub (optionnel)

Étape 4 — Migrer les workflows GitHub Actions

Étape 5 — Mettre à jour les remotes des laptops

Étape 6 — Recréer secrets et webhooks

Étape 7 — Migrer les contributeurs

Étape 8 — Période de double-écriture

Étape 9 — Couper GitHub définitivement

Adaptation Afrique de l’Ouest

Erreurs fréquentes

À lire ensuite

Etape 1 : evaluer ce que vous voulez vraiment migrer

Etape 2 : preparer un VPS Forgejo avec Docker Compose

Etape 3 : creer un token GitHub avec les bonnes portees

Etape 4 : lancer la migration via l’interface Forgejo

Etape 5 : verifier l’integrite du code et des branches

Etape 6 : migrer les Git LFS si vous en utilisez

Etape 7 : convertir les workflows GitHub Actions vers Forgejo Actions

Etape 8 : enregistrer un runner Forgejo Actions sur un VPS

Etape 9 : transferer les secrets et variables d’environnement

Etape 10 : rediriger les anciennes URLs GitHub vers Forgejo

Etape 11 : configurer les sauvegardes Forgejo automatisees

Etape 12 : former l’equipe et documenter les workflows

Etape 13 : auditer la consommation disque apres 30 jours

Etape 14 : monitorer la disponibilite avec Uptime Kuma

Ce que la migration préserve

Ce qui ne migre pas automatiquement

Étape 1 — Préparer côté GitHub

Étape 2 — Importer dans Forgejo

Étape 3 — Mirror push vers GitHub (optionnel)

Étape 4 — Migrer les workflows GitHub Actions

Étape 5 — Mettre à jour les remotes des laptops

Étape 6 — Recréer secrets et webhooks

Étape 7 — Migrer les contributeurs

Étape 8 — Période de double-écriture

Étape 9 — Couper GitHub définitivement

Adaptation Afrique de l’Ouest

Erreurs fréquentes

À lire ensuite

Etape 1 : evaluer ce que vous voulez vraiment migrer

Etape 2 : preparer un VPS Forgejo avec Docker Compose

Etape 3 : creer un token GitHub avec les bonnes portees

Etape 4 : lancer la migration via l’interface Forgejo

Etape 5 : verifier l’integrite du code et des branches

Etape 6 : migrer les Git LFS si vous en utilisez

Etape 7 : convertir les workflows GitHub Actions vers Forgejo Actions

Etape 8 : enregistrer un runner Forgejo Actions sur un VPS

Etape 9 : transferer les secrets et variables d’environnement

Etape 10 : rediriger les anciennes URLs GitHub vers Forgejo

Etape 11 : configurer les sauvegardes Forgejo automatisees

Etape 12 : former l’equipe et documenter les workflows

Etape 13 : auditer la consommation disque apres 30 jours

Etape 14 : monitorer la disponibilite avec Uptime Kuma

Articles Similaires

Traiter du texte en Bash : grep, sed et awk par l’exemple

Les regex en Python avec le module re

Déploiement continu sur un VPS avec GitHub Actions