Migrer d'Azure DevOps vers GitLab : le guide complet

La migration d'Azure DevOps vers GitLab peut sembler complexe, mais avec la bonne approche et les bons outils, le processus sera fluide et efficace. Ce guide détaille toutes les étapes pour migrer avec succès vos projets, dépôts et pipelines d'Azure DevOps vers GitLab.

Vue d'ensemble

GitLab propose à la fois Congregate (maintenu par les Services professionnels de GitLab) et une importation intégrée des dépôts Git pour migrer des projets depuis Azure DevOps (ADO). Ces options prennent en charge la migration dépôt par dépôt ou de façon groupée et préservent l'historique des commits git, les branches et les tags. Elles prennent également en charge des éléments supplémentaires tels que les wikis, les éléments de travail, les variables CI/CD, les images de conteneurs, les paquets, les pipelines et bien plus encore (matrice de fonctionnalités). Utilisez ce guide pour planifier et exécuter votre migration, puis accomplir les tâches de suivi post-migration.

Les entreprises qui migrent d'Azure DevOps vers GitLab suivent généralement une approche en plusieurs étapes :

• Elles migrent les dépôts d'Azure DevOps vers GitLab à l'aide de Congregate ou de la migration de dépôt intégrée à GitLab.
• Elles migrent les pipelines d'Azure Pipelines vers GitLab CI/CD.
• Elles migrent les éléments restants tels que les tableaux, les éléments de travail et les artefacts vers les tickets, registres de paquets et de conteneurs GitLab.

Phases de migration principales :

graph LR
    subgraph Prérequis
        direction TB
        A["Configurer le fournisseur d'identité (IdP)<br/>et provisionner les utilisateurs"]
        A --> B["Configurer les runners et<br/>les intégrations tierces"]
        B --> I["Former les utilisateurs et<br/>gérer le changement"]
    end
    
    subgraph MigrationPhase["Phase de migration"]
        direction TB
        C["Migrer le code source"]
        C --> D["Préserver les contributions et<br/>l'historique du format"]
        D --> E["Migrer les éléments de travail,<br/>mapper vers <a href="https://docs.gitlab.com/topics/plan_and_track/">GitLab Plan<br/>et suivre le travail"]
    end
    
    subgraph PostMigration["Étapes post-migration"]
        direction TB
        F["Créer ou traduire les<br/>pipelines ADO vers GitLab CI"]
        F --> G["Migrer les autres actifs,<br/>paquets et images de conteneurs"]
        G --> H["Introduire des améliorations SDLC et de <a href="https://docs.gitlab.com/user/application_security/secure_your_application/">sécurité</a><br/>"]
    end
    
    Prérequis --> MigrationPhase
    MigrationPhase --> PostMigration

    style A fill:#FC6D26
    style B fill:#FC6D26
    style I fill:#FC6D26
    style C fill:#8C929D
    style D fill:#8C929D
    style E fill:#8C929D
    style F fill:#FFA500
    style G fill:#FFA500
    style H fill:#FFA500

Planifiez votre migration

Pour planifier votre migration, posez-vous ces questions :

• Dans quels délais devons-nous achever la migration ?
• Comprenons-nous ce qui sera migré ?
• Qui exécutera la migration ?
• Quelle structure organisationnelle souhaitons-nous mettre en place dans GitLab ?
• Existe-t-il des contraintes, limitations ou pièges à prendre en compte ?

Déterminez votre calendrier, car il dictera en grande partie votre approche de migration. Identifiez des spécialistes ou des groupes familiarisés avec les plateformes Azure DevOps et GitLab (comme les « Early adopters ») pour faciliter l'adoption et fournir des conseils.

Faites l'inventaire de ce que vous devez migrer :

• Le nombre de dépôts, de pull requests et de contributeurs
• Le nombre et la complexité des éléments de travail et des pipelines
• Les tailles de dépôts et les relations de dépendance
• Les intégrations critiques et les exigences relatives aux runners (pools d'agents dotés de capacités spécifiques)

Utilisez l'outil Evaluate des Services professionnels de GitLab pour produire un inventaire complet de toute votre organisation Azure DevOps avec les dépôts, le nombre de pull requests, les listes de contributeurs, le nombre de pipelines, les éléments de travail, les variables CI/CD et bien plus encore. Si vous travaillez avec l'équipe des Services professionnels de GitLab, partagez ce rapport avec votre responsable de mission ou votre architecte technique pour faciliter la planification de la migration.

Le calendrier de migration est principalement déterminé par le nombre de pull requests, la taille des dépôts et le volume de contributions (par exemple, les commentaires dans les pull requests, les éléments de travail, etc.). 1 000 petits dépôts avec un nombre limité de pull requests et de contributeurs peuvent migrer beaucoup plus rapidement qu'un ensemble plus restreint de dépôts contenant des dizaines de milliers de pull requests et des milliers de contributeurs. Utilisez vos données d'inventaire pour estimer l'effort et planifier des tests avant de procéder aux migrations de production.

Comparez l'inventaire avec le calendrier souhaité et décidez si vous allez migrer tous les dépôts à la fois ou par lots. Si les équipes ne peuvent pas migrer simultanément, organisez les migrations par lots et échelonnez-les pour vous aligner sur les calendriers des équipes. Par exemple, lors des missions des Services professionnels, nous organisons des migrations par vagues de 200 à 300 projets pour limiter la complexité et respecter les limites de débit des API, à la fois dans GitLab et ADO.

L'outil d'importation de dépôt intégré de GitLab migre les dépôts Git (commits, branches et tags) un par un. Congregate est conçu pour préserver les pull requests (appelées merge requests dans GitLab), les commentaires et les métadonnées associées lorsque cela est possible ; l'importation simple de dépôt intégrée se concentre uniquement sur les données Git (historique, branches et tags).

Éléments nécessitant généralement une migration distincte ou une recréation manuelle :

• Pipelines Azure : créez des pipelines GitLab CI/CD équivalents (consultez la documentation YAML CI/CD et/ou les composants CI/CD). Vous pouvez également envisager d'utiliser la conversion de pipelines basée sur l'IA disponible dans Congregate.
• Éléments de travail et tableaux : mappez-les vers les tickets, epics et tableaux de tickets de GitLab.
• Artefacts, images de conteneurs (ACR) : migrez-les vers le registre de paquets ou le registre de conteneurs de GitLab.
• Hooks de service et intégrations externes : recréez-les dans GitLab.
• Les modèles de permissions diffèrent entre ADO et GitLab ; examinez et planifiez le mappage des permissions plutôt que de supposer une préservation exacte.

Examinez ce que chaque outil (Congregate vs importation intégrée) va migrer et choisissez celui qui correspond à vos besoins. Dressez une liste de toutes les données ou intégrations qui doivent être migrées ou recréées manuellement.

Qui exécutera la migration ?

Les migrations sont généralement exécutées par un propriétaire de groupe GitLab ou un administrateur d'instance, ou par une personne désignée ayant obtenu les permissions nécessaires relatives au groupe/projet de destination. Congregate et les API d'importation GitLab nécessitent des tokens d'authentification valides pour Azure DevOps et GitLab.

• Décidez si un propriétaire/administrateur de groupe effectuera les migrations ou si vous accorderez un accès délégué à une équipe/personne spécifique.
• Assurez-vous que la personne dédiée à la migration a correctement configuré les tokens d'accès personnels (Azure DevOps et GitLab) avec les portées requises par votre outil de migration choisi (par exemple, les portées api/read_repository et toute exigence spécifique à l'outil).
• Testez les tokens et les permissions avec une petite migration pilote.

Remarque : Congregate exploite la fonctionnalité d'importation basée sur des fichiers pour les migrations ADO et nécessite des permissions d'administrateur d'instance pour s'exécuter (consultez notre documentation). Si vous migrez vers GitLab.com, envisagez de faire appel aux Services professionnels. Pour plus d'informations, consultez leur catalogue complet. Un compte non-administrateur ne peut pas préserver l'attribution des contributions !

Quelle structure organisationnelle souhaitons-nous dans GitLab ?

Bien qu'il soit possible de mapper directement la structure ADO vers la structure GitLab, il est recommandé de rationaliser et de simplifier la structure pendant la migration. Réfléchissez à la façon dont les équipes travailleront dans GitLab et concevez la structure de façon à faciliter la collaboration et la gestion des accès. Voici un exemple de mappage de la structure ADO vers la structure GitLab :

graph TD
    subgraph GitLab
        direction TB
        A["Groupe principal"]
        B["Sous-groupe (facultatif)"]
        C["Projets"]
        A --> B
        A --> C
        B --> C
    end

    subgraph AzureDevOps["Azure DevOps"]
        direction TB
        F["Organisations"]
        G["Projets"]
        H["Dépôts"]
        F --> G
        G --> H
    end

    style A fill:#FC6D26
    style B fill:#FC6D26
    style C fill:#FC6D26
    style F fill:#8C929D
    style G fill:#8C929D
    style H fill:#8C929D

Approche recommandée :

• Mappez chaque organisation ADO à un groupe GitLab (ou un petit ensemble de groupes), et non à de nombreux petits groupes. Évitez de créer un groupe GitLab pour chaque projet d'équipe ADO et utilisez la migration comme une opportunité de rationaliser votre structure GitLab.
• Utilisez des sous-groupes et des permissions au niveau du projet pour regrouper les dépôts associés.
• Gérez l'accès à des ensembles de projets en utilisant les groupes et l'appartenance aux groupes (groupes et sous-groupes) de GitLab plutôt qu'un groupe par projet d'équipe.
• Examinez les permissions de GitLab et utilisez les liens de groupe SAML pour mettre en œuvre un modèle de contrôle d'accès basé sur les rôles (RBAC) d'entreprise pour votre instance GitLab (ou un espace de nommage GitLab.com).

Tableaux ADO et éléments de travail : état de la migration

Il est important de comprendre comment les éléments de travail migrent d'ADO vers GitLab Plan (tickets, epics et tableaux).

• Les tableaux et éléments de travail ADO sont mappés vers les tickets, epics et tableaux de tickets de GitLab. Planifiez comment vos workflows et configurations de tableaux seront migrés.
• Les epics et fonctionnalités ADO deviennent des epics GitLab.
• Les autres types d'éléments de travail (user stories, tâches, bogues) deviennent des tickets au niveau du projet.
• La plupart des champs standard sont préservés ; certains champs personnalisés sélectionnés peuvent être migrés lorsqu'ils sont pris en charge.
• Les relations parent-enfant sont conservées afin que les epics référencent tous les tickets associés.
• Les liens vers les pull requests sont convertis en liens de merge requests pour maintenir la traçabilité du développement.

Exemple d'une migration d'un élément de travail individuel vers un ticket GitLab, avec conservation des champs et relations :

Conseils pour la migration par lots :

• Si vous devez exécuter des migrations par lots, utilisez votre nouvelle structure de groupe/sous-groupe pour définir les lots (par exemple, par organisation ADO ou par domaine produit).
• Utilisez les rapports d'inventaire pour orienter la sélection des lots et testez chaque lot avec une migration pilote avant d'effectuer la migration complète.

Migration des pipelines

Congregate a récemment introduit une conversion basée sur l'IA pour les pipelines YAML multi-étapes d'Azure DevOps vers GitLab CI/CD. Cette conversion automatisée fonctionne avant tout pour les pipelines simples avec un fichier unique et est conçue pour fournir un point de départ fonctionnel plutôt qu'un fichier .gitlab-ci.yml prêt pour la production. L'outil génère un pipeline GitLab équivalent sur le plan fonctionnel que vous pouvez ensuite affiner et optimiser selon vos besoins.

• Conversion automatique des pipelines YAML Azure au format .gitlab-ci.yml
• Mieux adapté pour les configurations de pipeline simples avec un fichier unique
• Fichier passe-partout fourni pour accélérer la migration, pas un artefact de production final
• Revue et ajustement requis pour les scénarios complexes, les tâches personnalisées ou les exigences de l'entreprise
• Pas de prise en charge de pipelines de version classiques Azure DevOps, conversion en YAML multi-étapes nécessaire

Les propriétaires de dépôts doivent consulter la documentation GitLab CI/CD pour optimiser et améliorer davantage leurs pipelines après la conversion initiale.

Exemple de pipelines convertis :

      
# azure-pipelines.yml

trigger:
  - main

variables:
  imageName: myapp

stages:
  - stage: Build
    jobs:
      - job: Build
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self

          - task: Docker@2
            displayName: Build Docker image
            inputs:
              command: build
              repository: $(imageName)
              Dockerfile: '**/Dockerfile'
              tags: |
                $(Build.BuildId)

  - stage: Test
    jobs:
      - job: Test
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self

          # Example: run tests inside the container
          - script: |
              docker run --rm $(imageName):$(Build.BuildId) npm test
            displayName: Run tests

  - stage: Push
    jobs:
      - job: Push
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self

          - task: Docker@2
            displayName: Login to ACR
            inputs:
              command: login
              containerRegistry: '<your-acr-service-connection>'

          - task: Docker@2
            displayName: Push image to ACR
            inputs:
              command: push
              repository: $(imageName)
              tags: |
                $(Build.BuildId)


    

      
# .gitlab-ci.yml

variables:
  imageName: myapp

stages:
  - build
  - test
  - push

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $imageName:$CI_PIPELINE_ID -f $(find . -name Dockerfile) .
  only:
    - main

test:
  stage: test
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker run --rm $imageName:$CI_PIPELINE_ID npm test
  only:
    - main

push:
  stage: push
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker tag $imageName:$CI_PIPELINE_ID $CI_REGISTRY/$CI_PROJECT_PATH/$imageName:$CI_PIPELINE_ID
    - docker push $CI_REGISTRY/$CI_PROJECT_PATH/$imageName:$CI_PIPELINE_ID
  only:
    - main


    

Liste de contrôle finale :

• Décidez du calendrier et de la stratégie par lots.
• Produisez un inventaire complet des dépôts, pull requests et contributeurs.
• Choisissez Congregate ou l'importation intégrée en fonction de la portée (pull requests et métadonnées vs données Git uniquement).
• Décidez qui exécutera les migrations et assurez-vous que les tokens/permissions sont configurés.
• Identifiez les éléments qui doivent être migrés séparément (pipelines, éléments de travail, artefacts et hooks) et planifiez ces migrations.
• Effectuez des migrations pilotes, validez les résultats, puis passez à la migration complète selon votre calendrier.

Exécutez vos migrations

Une fois la planification terminée, exécutez les migrations par étapes, en commençant par des migrations d'essai, qui permettent de faire remonter les problèmes spécifiques à l'organisation tôt et de mesurer la durée, de valider les résultats et d'affiner votre approche avant la production.

Utilisez les migrations d'essai pour valider les éléments suivants :

• Succès de la migration d'un dépôt donné et des éléments associés (historique, branches, tags ; ainsi que les merge requests/commentaires si vous utilisez Congregate)
• Utilisation immédiate de la destination (permissions, runners, variables CI/CD, intégrations)
• Durée de chaque lot (afin de définir les calendriers et les attentes des parties prenantes)

Conseils concernant les temps d'arrêt :

• L'importation Git intégrée de GitLab et Congregate ne nécessitent pas intrinsèquement de temps d'arrêt.
• Pour les vagues de production, gelez les modifications dans ADO (protections de branches ou lecture seule) pour éviter les commits manqués, les mises à jour de pull requests ou les éléments de travail créés en cours de migration.
• Les essais n'ont pas besoin d'être gelés et peuvent être exécutés à tout moment.

Conseils pour la migration par lots :

• Exécutez des lots d'essai consécutifs pour raccourcir le temps écoulé ; laissez les équipes valider les résultats de manière asynchrone.
• Utilisez votre structure de groupe/sous-groupe planifiée pour définir les lots et respectez les limites de débit des API.

Étapes recommandées :

1. Créez une destination de test dans GitLab pour les essais :

• GitLab.com : créez un groupe/espace de nommage dédié (par exemple, my-org-sandbox).
• Instance auto-gérée : créez un groupe de niveau supérieur ou une instance de test distincte si nécessaire.

2. Préparez l'authentification :

• PAT Azure DevOps avec les portées requises.
• Token d'accès personnel GitLab avec api et read_repository (plus accès administrateur pour les importations basées sur des fichiers utilisées par Congregate).

3. Exécutez des migrations d'essai :

• Dépôts uniquement : utilisez l'importation intégrée de GitLab (dépôt par URL).
• Dépôts + pull requests/merge requests et actifs supplémentaires : utilisez Congregate.

4. Suivi post-essai :

• Vérifiez l'historique du dépôt, les branches, les tags ; les merge requests (si elles ont été migrées), les tickets/epics (s'ils ont été migrées), les labels et les relations.
• Vérifiez les permissions/rôles, les branches protégées, les approbations requises, les runners/tags, les variables/secrets, les intégrations/webhooks.
• Validez les pipelines (.gitlab-ci.yml) ou les pipelines convertis le cas échéant.

5. Demandez aux utilisateurs de valider la fonctionnalité et la fidélité des données.
6. Résolvez les problèmes découverts lors des essais et mettez à jour vos runbooks.
7. Réseau et sécurité :

• Si votre destination utilise des listes d'IP autorisées, ajoutez les IP de votre hôte de migration et tous les runners/intégrations requis afin de garantir la réussite des importations.

8. Exécutez les migrations de production par vagues :

• Appliquez des gels de modifications dans ADO pendant chaque vague.
• Surveillez la progression et les logs ; réessayez ou ajustez les tailles de lots si vous atteignez les limites de débit.

9. Facultatif : supprimez le groupe de l'environnement sandbox ou archivez-le après avoir terminé.

Références terminologiques pour GitLab et Azure DevOps