Migrer de GitLab vers fremforge

Ce guide couvre la migration de GitLab vers fremforge. Il s’applique à GitLab.com, à GitLab autogéré (CE ou EE) et à GitLab Dedicated. Les différences entre ces offres portent surtout sur la méthode d’authentification et sur les fonctionnalités propres à GitLab que vous avez pu activer.

Si vous venez de GitHub, lisez d’abord le guide de migration depuis GitHub. Certaines étapes de bon sens sont identiques et nous ne les répétons pas ici.

Si vous n’avez pas encore passé la liste de contrôle avant migration sur votre tenant GitLab actuel, commencez par là. Pour les migrations depuis GitLab, elle signale notamment les références include: inter-projets de GitLab CI (qu’il faut démêler à la main) et les déploiements GitLab Pages (qu’il faut héberger ailleurs, car fremforge n’a pas de produit Pages ; voir l’étape 6).

Avant de commencer

Ce dont vous avez besoin de votre côté :

• Un compte avec le rôle de propriétaire sur le ou les groupes GitLab que vous migrez.
• Un jeton d’accès personnel GitLab avec les portées api, read_repository, read_user et read_registry.
• Un accès administrateur à l’organisation fremforge vers laquelle vous migrez.
• Pour la migration de la CI : un inventaire des modèles GitLab CI, des références include: et des tags de GitLab Runner personnalisés dont dépendent vos pipelines.

Nos recommandations :

• Gelez les fusions dans les branches par défaut pendant la migration.
• Validez d’abord un dépôt de bout en bout. Les pipelines GitLab CI sont structurellement plus éloignés de Forgejo Actions que ne le sont les GitHub Actions ; le travail d’adaptation par dépôt est donc plus important.
• Si vos pipelines GitLab CI comportent de nombreuses références include: inter-projets, cartographiez le graphe de dépendances avant de commencer, afin de ne pas vous retrouver avec des pipelines à moitié migrés qui référencent des modèles qu’ils ne voient plus.

Estimation de durée :

• Un petit dépôt avec un .gitlab-ci.yml simple : 30 à 60 minutes, adaptation du pipeline comprise.
• Un dépôt moyen avec une CI de complexité modérée (DAG, needs:, tags de runners personnalisés) : 2 à 4 heures.
• Migration en masse de 20 à 50 dépôts dont beaucoup partagent des modèles include: GitLab CI : 3 à 5 jours d’ingénierie, principalement consacrés à la conversion de la CI.

Matrice de parité fonctionnelle

Pour la sécurité et l’authentification, la même matrice que la matrice de parité de la migration depuis GitHub s’applique : fremforge fournit les mêmes briques de sécurité quelle que soit la source. Par défaut, fremforge configure les nouvelles organisations en accès Git uniquement via HTTPS (SSH désactivé par défaut depuis le 2026-05-22), avec l’application OAuth Git Credential Manager préenregistrée ; les développeurs passent par la MFA de l’IdP de votre organisation à chaque renouvellement lors d’un push. Points propres à GitLab :

Étape 1 : migration des dépôts et de l’historique

L’importateur natif de Forgejo prend GitLab en charge comme source. Il copie l’historique Git complet, les tickets, les merge requests (importées comme pull requests), les commentaires, les étiquettes, les jalons, le contenu du wiki et les versions.

Avec l’importateur natif (via l’interface)

Depuis l’interface d’administration fremforge de votre organisation :

1. Cliquez sur + → Nouvelle migration.
2. Sélectionnez GitLab comme source.
3. Collez l’URL du projet GitLab (par exemple https://gitlab.com/acme/backend).
4. Collez votre jeton d’accès personnel GitLab.
5. Cochez les types de contenu à importer : Wiki, Issues, Merge requests, Releases, Labels, Milestones.
6. Choisissez l’organisation cible et le nom du dépôt sur fremforge.
7. Cliquez sur Migrate repository.

Avec l’API (pour les scripts)

# Build the JSON body via jq so the token is JSON-string-escaped safely
# (a token containing `"` or `\` would otherwise break the body).
jq -nc \
  --arg clone_addr "https://gitlab.com/acme/backend.git" \
  --arg auth_token "$GITLAB_TOKEN" \
  --arg repo_owner "acme" \
  --arg repo_name  "backend" \
  '{clone_addr: $clone_addr, auth_token: $auth_token,
    service: "gitlab", repo_owner: $repo_owner, repo_name: $repo_name,
    wiki: true, issues: true, pull_requests: true,
    releases: true, labels: true, milestones: true,
    lfs: true}' \
| curl -X POST "https://frem.sh/api/v1/repos/migrate" \
    -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
    -H "Content-Type: application/json" \
    -d @-

Correspondance des concepts GitLab avec fremforge

GitLab et Forgejo n’emploient pas le même vocabulaire. L’importateur gère les cas courants :

Sous-groupes

GitLab prend en charge des sous-groupes imbriqués à volonté. fremforge (Forgejo) utilise un modèle plat organisation + dépôt. Si votre structure GitLab est company / department / team / project, décidez avant la migration si vous préférez :

1. Tout regrouper dans une seule organisation : tous les projets deviennent des dépôts <company-slug>/<team>-<project> dans une même organisation. Permissions plus simples, mais une partie de la hiérarchie est perdue.
2. Une organisation par groupe de premier niveau : <company-department-slug> avec des noms de dépôts à plat. La hiérarchie au niveau des départements est perdue.
3. Une organisation par sous-groupe : davantage d’organisations, davantage de gestion des utilisateurs, chacune facturée séparément. Viable uniquement si les sous-groupes ont réellement des besoins de facturation et d’accès distincts.

L’importateur prend directement en charge les options 1 et 2. L’option 3 impose de créer plusieurs organisations fremforge et de lancer l’import N fois.

Étape 2 : secrets et variables CI/CD

GitLab stocke les variables CI/CD au niveau de l’instance, du groupe, du projet et de l’environnement. fremforge Actions prend en charge des secrets et variables d’organisation, d’environnement et de dépôt : une hiérarchie à trois niveaux qui correspond proprement aux cas courants de GitLab.

Important : les variables CI/CD GitLab marquées « masked » n’exportent pas leur valeur via l’API. Vous devez soit connaître la valeur, soit la récupérer dans votre référentiel de secrets. C’est la même contrainte que pour la migration des secrets GitHub.

Ressaisir les variables

Pour chaque variable CI/CD GitLab, posez-vous ces questions :

• S’agit-il d’un identifiant cloud de longue durée (clé d’accès AWS, secret de principal de service Azure, AK/SK T Cloud Public) ? Nous recommandons vivement de le remplacer par une fédération OIDC vers le cloud cible (voir l’étape 4 ci-dessous) plutôt que de migrer l’identifiant statique.
• S’agit-il d’une variable protégée (concept GitLab, accessible uniquement aux branches et tags protégés) ? fremforge propose l’équivalent avec les secrets d’environnement. Configurez l’environnement cible avec un accès conditionné à la protection de branche et placez le secret dans cette portée.
• S’agit-il d’une variable de type fichier (GitLab stocke le contenu d’un fichier multiligne dans une variable) ? fremforge permet la même chose avec le stockage de secrets standard. Collez le contenu multiligne ; le runner le met à disposition dans la variable d’environnement nommée au moment du job.

Définissez les variables et secrets dans l’interface d’administration fremforge, à la portée correspondante : Paramètres → Secrets (organisation) ou Dépôt → Paramètres → Secrets (dépôt).

Étape 3 : conversion de GitLab CI vers Forgejo Actions

C’est l’étape la plus lourde d’une migration depuis GitLab. Les pipelines GitLab CI sont structurellement différents de Forgejo Actions : stages, jobs, extends, include, rules, artifacts et cache ne correspondent pas un à un aux jobs, steps, needs et uses de GitHub Actions.

Il n’existe pas de convertisseur automatique. La conversion automatique figure sur la feuille de route, en fonction de la demande des clients. Au lancement, nous fournissons de la documentation et des modèles de conversion manuelle qui couvrent les cas courants.

Modèles de conversion

Stages → jobs avec needs:

GitLab CI organise les pipelines en étapes (stages) séquentielles. Forgejo Actions les organise en jobs parallèles avec des dépendances DAG explicites via needs:.

GitLab CI :

stages: [build, test, deploy]

build:
  stage: build
  script: make build

test:
  stage: test
  script: make test

deploy:
  stage: deploy
  script: make deploy

Équivalent Forgejo Actions (.forgejo/workflows/main.yaml) :

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: make build

  test:
    needs: build
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: make test

  deploy:
    needs: test
    runs-on: fremforge
    steps:
      - uses: actions/checkout@v4
      - run: make deploy

extends: → workflows réutilisables ou actions composites

extends: dans GitLab CI hérite de la configuration d’un job. Forgejo Actions propose deux équivalents :

1. Les workflows réutilisables (workflow_call) pour hériter de jobs entiers d’un workflow à l’autre.
2. Les actions composites (runs: using: composite) pour hériter de séquences d’étapes.

La conversion est manuelle : repérez le job parent .extends: dans GitLab, copiez son script: et sa préparation dans une action composite sous .forgejo/actions/<name>/action.yml, puis appelez-la avec uses: ./.forgejo/actions/<name> depuis les workflows qui l’utilisent.

Modèles inter-projets include:

include: project: dans GitLab CI récupère la configuration CI d’un autre projet. Il n’y a pas d’équivalent direct dans Forgejo Actions. Les workflows réutilisables (uses: owner/repo/.forgejo/workflows/template.yaml@ref) s’en rapprochent le plus et fonctionnent au sein d’une même organisation fremforge.

Pour les migrations qui comportent des projets de modèles partagés (fréquents dans les organisations dotées d’équipes plateforme CI), migrez d’abord le dépôt des modèles, puis mettez à jour les références uses: des dépôts consommateurs au moment de leur propre migration.

rules: et only:/except: → expressions if:

GitLab CI dispose de trois mécanismes qui se recoupent pour l’exécution conditionnelle des jobs. Forgejo Actions utilise la même syntaxe d’expression if: que GitHub Actions.

GitLab :

deploy:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success
    - when: never
  script: make deploy

Forgejo Actions :

deploy:
  if: github.ref == 'refs/heads/main'
  runs-on: fremforge
  steps:
    - uses: actions/checkout@v4
    - run: make deploy

artifacts: → upload-artifact / download-artifact

Dans GitLab CI, les artefacts se propagent automatiquement d’une étape à l’autre. Forgejo Actions exige un actions/upload-artifact explicite dans le job producteur et un actions/download-artifact dans le job consommateur.

cache: → actions/cache

cache: dans GitLab CI correspond à actions/cache@v4, avec la même sémantique de clé de cache et de clés de restauration.

services: → lancer les side-cars dans des étapes (PAS le bloc services: du workflow)

Les services: de GitLab CI (side-car Postgres, Redis, etc.) ne se traduisent PAS aujourd’hui par un bloc services: sur fremforge : Forgejo Actions ne prend que partiellement en charge le bloc services:. Les déclarations sont analysées sans erreur mais ne lancent jamais rien ; votre test se connectera donc à localhost:5432 et échouera. Les workflows qui dépendent du bloc services: natif ne fonctionneront pas.

La voie prise en charge consiste à lancer le side-car explicitement dans une étape : Docker est disponible sur le runner (voir Images de runner), donc un docker run -d postgres:16 dans une étape de préparation fonctionne. Plus couramment, on lance la dépendance directement avec ce que fournit l’écosystème du langage (Testcontainers pour Java, pytest-docker pour Python, testcontainers-go, etc.). Pour des topologies de test à plusieurs conteneurs, un appel à docker compose dans la VM, au sein d’une étape, est la pratique idiomatique.

La prise en charge native du bloc services: figure sur la feuille de route de la plateforme. D’ici là, la consigne de migration est la suivante : réécrivez les blocs services: de GitLab en docker run / docker compose / testcontainers dans des étapes, et non en blocs services: Forgejo.

Tags de runner

Les tags: de GitLab CI sélectionnent des runners précis. runs-on: dans Forgejo Actions fait la même chose. Les runners hébergés fournis par fremforge utilisent le label fremforge (voir Images de runner pour le système et les outils du runner). Les runners personnalisés peuvent s’enregistrer avec leurs propres labels, que runs-on: cible par leur nom.

Si votre GitLab CI reposait sur des runners privés précis (tags: [gpu], tags: [macos], tags: [on-prem]), ces runners personnalisés doivent être mis en place sur fremforge via le processus d’enregistrement des runners auto-hébergés (BYO). Les runners hébergés de fremforge sont uniquement Linux amd64 (voir Images de runner) ; GPU et macOS ne sont pas disponibles dans l’offre standard.

Étape 4 : fédération OIDC pour les déploiements

Si vos pipelines GitLab CI déploient sur une infrastructure cloud, la bonne pratique consiste à remplacer les identifiants de longue durée par une fédération OIDC. fremforge prend en charge nativement la fédération de jetons OIDC vers T Cloud Public ; pour AWS, Azure et GCP, les modèles standard de fédération OIDC fonctionnent.

Mise en place :

1. Dans l’interface d’administration fremforge, Paramètres → Fédération OIDC des runners → Add target.
2. Pour T Cloud Public : indiquez l’URN de l’agence cible. Le workflow du runner reçoit un JWT à durée de vie courte et à portée limitée, auquel l’agence T Cloud Public fait confiance et qu’elle échange contre des identifiants à portée limitée.
3. Pour AWS/Azure/GCP : configurez la confiance OIDC dans l’IAM du cloud cible avec https://frem.sh/_app/runner/oidc comme émetteur (un seul émetteur global pour tous les tenants ; l’isolation par tenant est assurée par la condition sur la revendication repository_owner, le modèle compatible avec GitHub Actions). Voir build/runners/oidc/ pour le point de terminaison JWKS, l’ensemble complet des revendications et des exemples de politiques de confiance par cloud.

Une fois la configuration faite, les workflows utilisent la fédération au lieu de clés statiques. Chaque job de runner reçoit un jeton d’identité OIDC à durée de vie courte sur $ACTIONS_ID_TOKEN_REQUEST_URL ; échangez-le contre des identifiants T Cloud Public à portée limitée au début du job :

- name: Federate to T Cloud Public
  run: |
    OIDC_TOKEN="$(curl -sSf -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
      "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=tcloud-${ORG_SLUG}")"
    CREDS_JSON="$(curl -sSf -X POST \
      "https://iam.eu-de.otc.t-systems.com/v3.0/OS-FEDERATION/token-exchange" \
      -H 'Content-Type: application/json' \
      -d "{\"identity\":{\"id_token\":{\"id\":\"$OIDC_TOKEN\"}},\"scope\":{\"agency\":{\"name\":\"fremforge-deploy\",\"domain\":{\"name\":\"$TCLOUD_DOMAIN\"}}}}")"
    {
      echo "TCLOUD_AK=$(jq -r '.credential.access' <<<"$CREDS_JSON")"
      echo "TCLOUD_SK=$(jq -r '.credential.secret' <<<"$CREDS_JSON")"
      echo "TCLOUD_TOKEN=$(jq -r '.credential.securitytoken' <<<"$CREDS_JSON")"
    } >> "$GITHUB_ENV"

Une action d’encapsulation qui masque l’appel curl est prévue ; la forme en ligne ci-dessus laisse le contrat OIDC brut visible et fonctionne dès aujourd’hui.

Supprimez les secrets d’identifiants statiques correspondants, dans GitLab comme dans fremforge.

Étape 5 : réenregistrement des clés SSH

Même processus qu’à l’étape 4 de la migration depuis GitHub. Chaque développeur ajoute sa clé publique SSH à son compte fremforge.

Les autorités de certification SSH (fonctionnalité de GitLab EE) s’importent via <your-org>/_admin/auth-policy : la section CA SSH se trouve sous l’interrupteur « Autoriser le protocole SSH » (intégrée à la politique d’authentification le 2026-05-26). C’est la même interface d’administration que pour la migration depuis GitHub ; voir la section sur l’autorité de certification SSH pour la mise en place.

Étape 6 : GitLab Pages → hébergement externe (pas d’équivalent Pages dans Forgejo)

fremforge ne propose pas de produit Pages. Forgejo en amont n’a pas de module Pages et nous n’en avons pas développé. Les migrations GitLab Pages doivent aboutir ailleurs ; choisissez l’option adaptée à votre cas :

1. Documentation Markdown publiée dans un site Pages adossé au wiki d’un dépôt : activez le wiki de documentation publique de fremforge sur le dépôt migré. Le wiki sur frem.sh/<org>/<repo>/wiki[/...] sert du Markdown rendu, avec lecture anonyme activée par dépôt. Remarque : il sert du Markdown rendu, pas du HTML/JS statique arbitraire ; il couvre donc les sites Pages de type documentation, pas les déploiements Pages d’applications monopages.

2. Sites statiques HTML/JS (applications monopages, sortie Hugo / Jekyll / Astro) : hébergez-les à l’extérieur et pointez-y un CNAME depuis votre propre domaine. Parmi les choix raisonnables et compatibles avec l’UE : Bunny Edge Storage + Bunny CDN (la pile qu’utilise le site marketing de fremforge), Cloudflare Pages, Netlify ou Vercel. Rebranchez la construction via des workflows de runner fremforge qui déploient à chaque push.

3. Domaine personnalisé uniquement : si vous utilisiez GitLab Pages pour le certificat TLS du domaine personnalisé (plutôt que pour son étape de construction), pointez votre DNS vers votre hébergeur externe et réutilisez la fédération OIDC des runners fremforge pour déployer directement depuis le workflow, sans passer par un proxy fremforge.

Si votre pipeline GitLab Pages n’est pas trivial (CI personnalisée, redirections, déploiements par branche), écrivez à support@frem.sh : nous pouvons discuter de la bonne forme d’hébergement externe pour votre cas avant que vous ne vous engagiez dans un plan de migration.

Étape 7 : reconnexion des intégrations tierces

Les intégrations GitLab (cibles de webhooks, synchronisation Jira, notifications Slack, etc.) se reconnectent de la même façon qu’à l’étape 5 de la migration depuis GitHub. La plupart des intégrations prennent en charge Forgejo d’emblée.

Intégrations propres à GitLab sans équivalent direct :

• Agrégation du GitLab Security Dashboard : la vue Résultats de l’interface d’administration fremforge remplit le même rôle pour la chaîne d’approvisionnement intégrée.
• Value Stream Analytics / métriques DORA : fremforge fournit les métriques DORA (fréquence de déploiement, délai de mise en production, taux d’échec des changements, MTTR) ; voir Administration de l’organisation → DORA. Aucun outil externe n’est nécessaire, grâce aux événements de webhook et à l’interrogation de l’API.

Étape 8 : vérifier et décommissionner

Comme à l’étape 7 de la migration depuis GitHub :

1. Clonez, construisez, vérifiez que les tests passent.
2. Faites passer une PR d’essai par l’analyseur pre-receive, l’analyseur de dépendances et la vérification des commits signés.
3. Vérifiez que les webhooks sont bien livrés.
4. Vérifiez la connexion SSO de chaque utilisateur.
5. Mettez à jour la documentation avec les nouvelles URL.
6. Après 30 jours de fonctionnement sans problème, archivez les projets GitLab (ne les supprimez pas).

Pièges courants propres aux migrations depuis GitLab

La conversion des pipelines prend plus de temps que prévu.

Un .gitlab-ci.yml complexe, avec de nombreuses étapes, des DAG, extends:, include: et services:, peut demander une demi-journée par dépôt pour être porté correctement. Comptez 2 à 4 heures par pipeline de complexité moyenne. La matrice de compatibilité sur docs.frem.sh/marketplace-compat est centrée sur GitHub Actions ; pour les modèles propres à GitLab CI, utilisez l’étape 3 de ce guide et la documentation de Forgejo Actions.

Règles d’approbation des merge requests

Les règles d’approbation de GitLab (N approbateurs requis, groupes d’approbateurs précis, approbation fondée sur les code owners) correspondent aux règles de protection de branche de Forgejo, avec une granularité moindre. Si votre projet GitLab dépend de règles d’approbation sophistiquées (par exemple « des approbateurs différents pour les chemins sensibles du point de vue de la sécurité »), vérifiez avant la migration que le modèle de relecteurs obligatoires fondé sur CODEOWNERS de Forgejo vous suffit.

Fonctionnalités GitLab Premium/Ultimate

fremforge fournit un équivalent direct à la License Compliance de GitLab : l’analyse des licences exécute la détection de licences de Trivy sur chaque PR, classe chaque dépendance selon une catégorie de politique SPDX et peut bloquer la fusion en cas de licence interdite ou restreinte ; les résultats apparaissent sous Sécurité › Résultats › Licences. Pour le reste de la suite de sécurité de GitLab Ultimate (DAST, fuzzing, SAST avec les règles de sévérité d’Ultimate, Dependency Firewall, tableaux de bord de sécurité au niveau du groupe), fremforge ne propose pas d’équivalent direct ; toutefois le SAST (OpenGrep), l’analyse des dépendances et des CVE (osv-scanner) et l’analyse des conteneurs (Trivy) couvrent les cas les plus courants. Consultez l’article sur notre position en matière d’IA sur www.frem.sh et la page produit de fremforge pour savoir ce que nous couvrons et ce que nous excluons explicitement.

Runners GitLab tagués pour des contextes de conformité

Les tags de GitLab Runner comme compliance, restricted-network ou no-internet servent souvent à désigner des runners qui ne peuvent pas joindre l’internet public. Les runners hébergés de fremforge respectent cette contrainte par conception : les directives uses: se résolvent via les miroirs d’actions exclusivement européens sur https://frem.sh/<owner>/<repo> (la référence se trouve dans la page de migration depuis GitHub, §Étape 3 : adaptation des workflows Actions), et la sortie par le proxy sortant est limitée à ce miroir, aux registres de paquets mis en miroir et aux webhooks sortants du tenant client. Si votre contexte de conformité impose des runners sans aucun accès internet, utilisez des runners auto-hébergés sur votre propre réseau et pointez-les vers le point de terminaison d’enregistrement des runners de fremforge.

Obtenir de l’aide

Écrivez à support@frem.sh avec l’objet MIGRATION, GITLAB, <your-specific-issue>. Les clients de la première heure ont un accès direct à l’équipe de développement.

Voir aussi : Guide de migration depuis GitHub · Guide de migration depuis Azure DevOps · Matrice de compatibilité des 20 principales actions de la Marketplace · Liste de contrôle avant migration.