Migrer de GitHub vers GitLab : mode d'emploi

Si vous envisagez de passer de GitHub à GitLab, la première question qui se pose est presque toujours la même : Quelle est la complexité de la migration ? Pour la plupart des équipes DevSecOps, la crainte d'un travail fastidieux constitue le principal obstacle qui les sépare d'une plateforme DevSecOps unifiée d'IA native.

Migrer vers GitLab n'a jamais été aussi simple. L'outil d'importation intégré de GitLab transfère automatiquement et en arrière-plan la grande majorité des données de vos projets. Par ailleurs, la conversion de votre pipeline CI/CD, une tâche qui nécessitait traditionnellement une intervention humaine, est désormais en grande partie prise en charge par GitLab Duo. GitLab Duo, notre assistant d'IA native, peut convertir les workflows GitHub Actions en pipelines GitLab CI/CD.

Dans cet article, nous vous guidons à travers l'ensemble du processus de migration.

🎯 Migrez de GitHub vers GitLab dès aujourd'hui !

Quelles données sont migrées de GitHub vers GitLab ?

L'outil d'importation GitHub intégré à GitLab est accessible directement depuis l'interface de création de projet de GitLab et s'exécute en arrière-plan, ce qui vous permet de lancer une importation et de vaquer à vos occupations. La plupart des données de votre projet sont transférées automatiquement. Un ensemble plus restreint d'éléments correspond à des options facultatives ou présente des limitations qu'il est utile de connaître à l'avance.

Le tableau ci-dessous détaille les éléments migrés et leur mode de transfert :

Comment les rôles sont-ils mappés ?

GitHub et GitLab utilisent des conventions de nommage différentes ; un mappage est donc effectué lors de la migration. Lors de l'importation des collaborateurs, les rôles GitHub sont associés aux rôles GitLab de la façon suivante :

Prérequis

Les prérequis se sont simplifiés au fil des années. Il n'est notamment plus nécessaire que chaque auteur GitHub dispose d'une adresse e-mail publique correspondante sur GitLab. GitLab gère désormais automatiquement l'attribution grâce au mappage des contributions des utilisateurs (GitLab 17.8 et versions ultérieures). Vous trouverez plus d'informations à ce sujet ci-dessous.

Pour importer depuis GitHub.com ou GitHub Enterprise Server vers GitLab.com ou une instance GitLab Self-Managed, vous avez besoin :

• D'un accès au projet GitHub source que vous souhaitez importer.
• Du rôle de chargé de maintenance ou de propriétaire au sein du groupe GitLab de destination.
• De la source d'importation GitHub activée. Elle est activée par défaut sur GitLab.com ; sur GitLab Self-Managed, un administrateur doit l'activer dans les sources d'importation.
• L'organisation GitHub ne doit pas restreindre l'accès aux applications tierces (ou vous devez lui accorder l'accès lors de l'autorisation).

Quelques prérequis spécifiques à certaines situations :

• Vous souhaitez importer des objets Git LFS ? Activez LFS sur le projet de destination avant de lancer l'importation.
• Vous souhaitez importer des collaborateurs ? Vous devez disposer de la portée read:org sur votre token et d'au moins un accès Écriture ou Gestion sur le projet GitHub.

Les adresses e-mail correspondantes ne sont plus nécessaires

Auparavant, l'historique des contributions n'était correctement transféré que si l'adresse e-mail publique de chaque utilisateur GitHub correspondait à son adresse e-mail GitLab. Désormais, GitLab crée des utilisateurs fictifs pour tout auteur, assigné ou relecteur GitHub ne disposant pas de compte GitLab correspondant, et préserve leurs contributions.

Après l'importation, un propriétaire ou chargé de maintenance du groupe accède à Membres → Espaces réservés et réassigne chaque utilisateur fictif à l'utilisateur GitLab réel, qui accepte ensuite la réassignation. Vous pouvez ainsi effectuer la migration en premier et régler la question de l'attribution ultérieurement.

Réaliser l'importation

Trois méthodes permettent de lancer l'importation. Choisissez celle qui correspond à votre source et à votre échelle.

Méthode 1 : l'interface utilisateur avec GitHub OAuth (recommandée pour GitLab.com)

C'est la méthode la plus rapide pour la plupart des équipes.

1. Accédez à un groupe et sélectionnez Créer un projet → Importer un projet → GitHub (ou accédez directement à gitlab.com/projects/new#import_project).
2. Cliquez sur le bouton S'authentifier avec GitHub et approuvez l'application OAuth.
3. Pour les dépôts d'organisation, cliquez sur Accorder à côté du nom de l'organisation pour autoriser l'accès.
4. Filtrez vos dépôts à l'aide des onglets Propriétaire / Collaborateur / Organisation, puis sélectionnez les dépôts à importer. Vous pouvez les renommer et choisir l'espace de nommage GitLab cible.
5. Configurez les options facultatives (voir le tableau ci-dessous), puis cliquez sur Importer. L'importation s'exécute en arrière-plan ; vous pouvez quitter la page et revenir vérifier l'avancement ultérieurement.

Options facultatives :

Méthode 2 : jeton d'accès personnel (lorsque OAuth n'est pas configuré)

Si OAuth n'est pas configuré, authentifiez-vous à l'aide d'un jeton.

1. Créez un jeton d'accès personnel classique sur github.com/settings/tokens/new avec la portée repo (ajoutez read:org si vous importez des collaborateurs ou des objets LFS). Remarque : les jetons d'accès à granularité fine ne sont pas pris en charge.
2. Dans GitLab, accédez à un groupe et sélectionnez Créer un projet → Importer un projet → GitHub.
3. Collez le jeton, sélectionnez S'authentifier, puis suivez les mêmes étapes de sélection et de configuration que pour la méthode OAuth.

Méthode 3 : l'API REST (importations en masse et scripts)

Pour migrer de nombreux dépôts simultanément, automatiser un transfert ou importer des dépôts publics dont vous n'êtes pas propriétaire, utilisez l'API d'importation.

      curl --request POST \
  --url "https://gitlab.com/api/v4/import/github" \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "personal_access_token": "<github_classic_pat>",
    "repo_id": 12345678,
    "target_namespace": "my-group",
    "new_name": "imported-project",
    "optional_stages": {
      "single_endpoint_notes_import": true,
      "attachments_import": true,
      "collaborators_import": true
    }
  }'

    

Suivez la progression avec :

      curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/projects/<project_id>/import"

    

Vous aurez besoin d'un jeton d'accès personnel GitHub classique avec la portée repo et d'un jeton d'accès personnel GitLab avec la portée api.

Vérification de l'importation

Une fois l'importation terminée, effectuez une vérification rapide :

1. Ouvrez le nouveau projet et observez la bannière de statut passer par les étapes planifié → démarré → terminé. Si elle indique terminé partiellement, examinez les entités ayant échoué.
2. Comparez le nombre de branches, de tags, de SHA de commits, de tickets, de merge requests, de labels et de jalons avec la source.
3. Vérifiez que les éléments importés portent le badge Importé.

Une nouvelle importation crée une nouvelle copie (il n'est pas possible d'importer dans un projet existant) ; par conséquent, si quelque chose semble incorrect, supprimez le projet et relancez l'importation.

Faire coexister GitHub et GitLab lors d'une migration progressive

La migration ne doit pas nécessairement se faire d'un seul coup. La plupart des équipes procèdent progressivement, en conservant GitHub actif le temps de mettre en place GitLab, de valider les pipelines et de faire migrer les équipes une par une. GitLab est conçu pour coexister avec GitHub pendant cette transition, ce qui vous permet de l'adopter progressivement plutôt que de tout transférer d'un coup.

Voici les principales façons dont les deux plateformes fonctionnent en parallèle pendant la migration :

• Maintien de la synchronisation des dépôts grâce à la mise en miroir par pull. GitLab peut mettre en miroir un dépôt GitHub par pull, en récupérant automatiquement les nouvelles branches et les nouveaux commits selon un calendrier défini. Les équipes de développement peuvent continuer à effectuer des push vers GitHub, tandis que GitLab reste à jour, vous offrant ainsi une copie en lecture seule et en temps réel pour tester vos pipelines CI/CD et vos workflows avant que quiconque ne modifie ses habitudes. Lorsque vous êtes prêt à tout transférer, vous pouvez passer à la mise en miroir par push afin que les modifications apportées dans GitLab soient répercutées sur GitHub pour les équipes qui y travaillent encore.
• Exécution des pipelines sur des dépôts GitHub avec le CI/CD pour les dépôts externes. Si vous souhaitez évaluer GitLab CI/CD avant de déplacer le code, le CI/CD pour les dépôts externes connecte un dépôt GitHub à GitLab et exécute des pipelines à chaque push et pull request, en renvoyant le statut vers GitHub. Vous pouvez ainsi valider la conversion de votre fichier .gitlab-ci.yml à l'aide de commits réels, tandis que la source de vérité reste encore hébergée sur GitHub.
• Publication du statut CI/CD vers GitHub. Grâce à l'intégration GitHub, GitLab envoie les mises à jour de statut des pipelines et des commits à GitHub, de sorte que les équipes de développement qui n'ont pas encore migré voient toujours les indicateurs de réussite et les résultats de build dans l'interface qu'ils utilisent déjà.
• Migration équipe par équipe, dépôt par dépôt. L'outil d'importation fonctionnant projet par projet, vous pouvez commencer par migrer les dépôts d'une équipe, leur laisser le temps de s'adapter, puis migrer le groupe suivant une fois les éventuels problèmes résolus. Les groupes et sous-groupes qui n'ont pas encore été migrés peuvent continuer à pointer vers GitHub en attendant.

Migrer de GitHub Actions vers GitLab CI/CD

Le CI/CD est l'une des étapes de la migration qui n'est pas automatique. C'est l'occasion pour vous de moderniser vos pipelines. De nombreux concepts fondamentaux s'alignent entre les deux plateformes :

Une différence clé à garder à l'esprit : dans GitLab, les étapes s'exécutent de manière séquentielle et les jobs au sein d'une étape s'exécutent en parallèle, et vous pouvez utiliser needs: pour construire un graphe orienté acyclique (DAG) explicite.

La méthode rapide : laisser GitLab Duo convertir vos workflows

GitLab Duo Agent Platform inclut un flow Convert to GitLab CI/CD qui transforme vos workflows GitHub Actions en .gitlab-ci.yml, vous permettant ainsi de relire un brouillon plutôt que de tout réécrire de zéro.

GitLab Duo vous accompagne tout au long de la migration, pas seulement lors de la conversion :

• Planification : générez un plan de migration par dépôt et une évaluation de la complexité à partir de vos fichiers de workflow.
• Conversion : le flow Convert to GitLab CI/CD réécrit les workflows GitHub Actions en pipelines GitLab CI/CD, en préservant les builds matriciels, les dépendances entre les jobs, les artefacts et les règles conditionnelles.
• Documentation : mettez à jour les fichiers README, les badges et les liens (par exemple, « Pull Request » → « Merge Request »).
• Validation : recoupez les nombres d'éléments importés et identifiez les éventuels manquants.
• Débogage : le flow Fix CI/CD Pipeline analyse un job en échec, identifie la cause probable et prépare les modifications recommandées.
• Optimisation : recommandez des optimisations natives à GitLab telles que la mise en cache, les DAG avec needs: et les composants CI/CD.

GitLab Duo Agentic Chat peut extraire le contexte de vos tickets, merge requests et pipelines pour répondre à vos questions directement dans la plateforme, et GitLab Duo Code Suggestions vous assiste lorsque vous modifiez le fichier .gitlab-ci.yml dans le Web IDE.

Si GitLab Duo n'est pas disponible dans votre environnement, ces mêmes conversions fonctionnent bien avec un modèle de pointe en utilisant un prompt structuré. Voici un prompt qui produit des résultats fiables :

Convertis ce workflow GitHub Actions en GitLab CI/CD. Conserve les builds matriciels, les dépendances entre jobs, les artefacts et les règles conditionnelles. Renvoie un fichier .gitlab-ci.yml valide.

Quelques précautions lors de l'utilisation d'un assistant d'IA pour la migration : ne collez jamais de secrets, de jetons ou de noms d'hôtes internes ; validez toujours le YAML généré à l'aide de l'outil CI Lint de GitLab ; et traitez le résultat comme un brouillon à réviser, non comme un commit définitif.

La méthode manuelle : un exemple comparatif

Que GitLab Duo génère le code ou que vous l'écriviez vous-même, il est utile de visualiser la correspondance. Voici un workflow GitHub Actions typique de build et de test :

      name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '18' }
      - run: npm install
      - run: npm test
      - run: npm run build

    

Ci-dessous l'équivalent avec GitLab CI/CD. Notez que le checkout disparaît (GitLab se charge du clonage), runs-on devient image et chaque étape devient une ligne dans script: :

      stages: [test, build]

# GitLab-maintained SAST is one line away
# a nice upgrade to add during migration.
include:
  - template: Jobs/SAST.gitlab-ci.yml

test:
  stage: test
  image: node:18
  script:
    - npm install
    - npm test

build:
  stage: build
  image: node:18
  script:
    - npm install
    - npm run build
  artifacts:
    paths: [dist/]

    

Les builds matriciels se traduisent tout aussi directement : strategy.matrix devient parallel.matrix :

      test:
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ['16', '18', '20']
  script:
    - npm install
    - npm test

    

Et les déploiements conditionnels correspondent à rules: :

      deploy:
  stage: deploy
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

    

Dès que vous effectuez un commit du fichier .gitlab-ci.yml, GitLab exécute immédiatement le pipeline. Pour en savoir plus, consultez notre documentation sur GitLab CI/CD.

Depuis quelles autres plateformes GitLab peut-elle effectuer une importation ?

GitHub n'est pas la seule source. L'outil d'importation de GitLab prend en charge la migration depuis plusieurs autres plateformes :

• Bitbucket Cloud
• Bitbucket Server (Stash)
• FogBugz
• Gitea
• Dépôt par URL
• Fichier manifeste (AOSP)
• Jira (tickets uniquement)

Nous disposons également d'une documentation couvrant les migrations depuis :

• SVN
• ClearCase
• CVS
• Perforce
• TFVC

Merci de votre attention ! La migration n'a pas à être la partie redoutée de l'adoption d'une nouvelle plateforme. GitLab transfère vos données automatiquement, et GitLab Duo prend en charge la conversion CI/CD, vous permettant ainsi de vous concentrer sur la livraison. Pour aller plus loin, consultez les liens suivants :

• Essai gratuit de GitLab Duo Agent Platform
• Documentation sur la migration de projets de GitHub vers GitLab
• Outils d'importation de projets disponibles
• GitLab Duo Agent Platform
• Documentation GitLab CI/CD