Planification de votre migration vers GitHub

À propos des migrations

Si vous passez d’un produit GitHub comme GitHub Enterprise Server à GitHub Enterprise Cloud, ou d’une autre plateforme d’hébergement de code, comme Bitbucket Server ou GitLab, à GitHub, vous voudrez apporter votre travail avec vous : votre code, l’historique du code, et toutes vos conversations et collaboration passées.

Ce guide vous guide tout au long de la planification et de l’exécution d’une migration réussie. Vous allez découvrir comment préparer une migration, les outils disponibles pour déplacer vos données et comment réussir à les déplacer.

Terminologie relative à la migration

Avant d’utiliser ce guide pour planifier votre migration, apprenez ces termes importants.

Terme	Définition
Plateforme d’hébergement de code	Outil en ligne que vous utilisez pour héberger vos dépôts de code source et collaborer, par exemple GitHub Enterprise Cloud, GitHub Enterprise Server, Bitbucket Server et GitLab.com.
Système de gestion de versions	Outil que vous utilisez pour suivre et gérer les modifications apportées à votre code source sur l’ordinateur où vous effectuez ces modifications. Par exemple, si vous utilisez GitHub ou GitLab comme plateforme d’hébergement de code, vous utilisez le système de gestion de versions Git. Si vous utilisez Azure DevOps comme plateforme d’hébergement de code, vous pouvez utiliser Git ou Team Foundation Version Control (TFVC) comme système de gestion de versions sous-jacent. Vous pouvez aussi n’utiliser aucun système de gestion de versions.
Origine de migration	Endroit à partir duquel vous effectuez la migration. Il s’agit généralement d’une plateforme d’hébergement de code, mais cela peut être aussi bien votre propre ordinateur ou un lecteur réseau partagé.
Destination de migration	Produit GitHub auquel vous passez.
Chemin de migration	Combinaison de l’origine de votre migration et de la destination de votre migration, par exemple « Bitbucket Server vers GitHub Enterprise Cloud ». Pour certains chemins de migration, GitHub propose des outils spécialisés, tels que GitHub Enterprise Importer, pour vous aider à effectuer une migration.

Définition de l’étendue de votre migration

Avant de pouvoir planifier votre migration, vous devez comprendre ce que vous souhaitez migrer et quand.

Définition de votre origine et de votre destination

Tout d’abord, déterminez d’où vous devez déplacer les données. Il s’agit généralement, mais pas toujours, d’une plateforme d’hébergement de code.

Votre plateforme d’hébergement de code peut être un produit GitHub, comme GitHub.com ou GitHub Enterprise Server, ou une autre plateforme d’hébergement de code, comme Bitbucket Server, GitLab ou Azure DevOps. Selon la taille et la complexité de votre société, vous pouvez utiliser plusieurs plateformes d’hébergement de code différentes.

Si vous n’utilisez aucune plateforme d’hébergement de code, vous pouvez stocker votre code sur un lecteur réseau partagé, par exemple.

Quel que soit l’endroit de votre code, c’est votre « origine de migration ».

Vous devez également savoir vers quel produit GitHub vous effectuez la migration, ou votre « destination de migration ». Il peut s’agir de GitHub.com, qui comprend GitHub Enterprise Cloud, ou GitHub Enterprise Server.

Création d’un inventaire simple des dépôts que vous souhaitez migrer

Une fois que vous avez identifié l’origine et la destination de votre migration, déterminez les données à migrer.

Vous devez créer un inventaire de migration avec une liste de tous les dépôts de votre ou vos origines de migration que vous devez migrer. Nous vous recommandons d’utiliser une feuille de calcul. Comme point de départ, vous devriez consigner les données suivantes pour chaque dépôt :

• Nom
• Propriétaire : dans GitHub, il s’agit d’une organisation, mais dans d’autres outils, il peut y avoir un type de propriétaire différent
• URL
• Horodatage de la dernière mise à jour
• Nombre de demandes de tirage (ou équivalent dans votre origine de migration)
• Nombre de problèmes (ou équivalent dans votre origine de migration)

Si vous effectuez une migration à partir de GitHub Enterprise Cloud ou de GitHub Enterprise Server, vous pouvez obtenir ces données avec l’extension gh-repo-stats pour l’GitHub CLI. Avec seulement quelques commandes, gh-repo-stats se connecte à l’API de votre origine de migration et crée un fichier CSV avec tous les champs recommandés. Pour plus d’informations, consultez le dépôt mona-actions/gh-repo-stats.

Si vous effectuez une migration à partir d’Azure DevOps, nous vous recommandons la commande inventory-report dans les ADO2GH extension of the GitHub CLI. La commande inventory-report se connecte à l’API Azure DevOps et crée un fichier CSV très simple avec certains des champs suggérés ci-dessus. Pour plus d’informations sur l’installation de ADO2GH extension of the GitHub CLI, consultez « Migration de référentiels d’Azure DevOps vers GitHub Enterprise Cloud ».

Si vous effectuez une migration à partir du centre de données Bitbucket Server ou Bitbucket, nous vous recommandons la commande inventory-report dans les BBS2GH extension of the GitHub CLI. La commande inventory-report utilise l’API de votre instance Bitbucket pour générer un fichier CSV simple. Pour plus d’informations sur l’installation de BBS2GH extension of the GitHub CLI, consultez « Migration de dépôts de Bitbucket Server vers GitHub Enterprise Cloud ».

Pour les autres origines de migration, créez votre inventaire de migration vous-même. Vous pouvez créer la feuille de calcul avec les outils de reporting de l’origine, le cas échéant, ou avec l’API, ou créer l’inventaire manuellement.

Quelle que soit l’approche choisie pour votre inventaire de migration, notez le processus que vous avez suivi ou les commandes que vous avez exécutées. Vous voudrez très certainement ré-effectuer votre inventaire à mesure que vous continuez à planifier votre migration.

Une fois que vous avez la liste de tous vos dépôts, vous pouvez choisir ceux que vous souhaitez migrer. Une option consiste à migrer absolument tout. Toutefois, une migration est une excellente occasion d’évaluer vos dépôts et de supprimer tous les dépôts dont vous n’avez plus besoin. Nous constatons que de nombreuses sociétés ont des centaines, voire des milliers de dépôts inutilisés et inutiles, et les archiver peut simplifier grandement votre migration.

Mesure de la taille de vos dépôts

Une fois que vous avez terminé votre inventaire de migration de base, collectez des informations sur la taille de vos dépôts. Si vos dépôts sont grands ou contiennent des fichiers individuels de plus de 100 Mo, cela peut rendre votre migration plus longue et plus risquée et limiter les outils de migration disponibles.

Si vous utilisez Git comme système de gestion de versions, ce ne sont pas seulement les gros fichiers qui sont actuellement dans le dépôt qui comptent ; les gros fichiers de l’historique de votre dépôt comptent également. Par exemple, si vous aviez un fichier supérieur à 100 Mo dans votre dépôt, ce fichier est toujours présent dans votre historique Git, sauf si vous avez réécrit l’historique pour supprimer toutes les traces du fichier. Pour plus d’informations sur la réécriture de l’historique, consultez « À propos des fichiers volumineux sur GitHub ».

Si vous avez utilisé gh-repo-stats pour créer votre inventaire, vous avez déjà des informations de base sur la taille de vos dépôts. Pour créer un inventaire de migration complet, vous devez obtenir des informations plus détaillées sur les données qui sont dans vos dépôts.

Suivez ensuite les instructions ci-dessous pour ajouter les données suivantes à votre inventaire de migration pour chaque dépôt :

• Taille du fichier le plus gros (également appelé « blob »)
• Taille totale de tous les fichiers (« blobs »)

Si vous utilisez un système de gestion de versions autre que Git, ou si vos fichiers ne sont suivis avec aucun système de gestion de versions, commencez par déplacer les dépôts vers Git. Pour plus d’informations, consultez « Ajout de code hébergé localement dans GitHub ».

Ensuite, utilisez l’outil open source, git-sizer, pour obtenir ces données pour votre dépôt.

Prérequis

1. Installez git-sizer. Pour plus d’informations, consultez le dépôt github/git-sizer.
2. Pour vérifier que git-sizer est installé, exécutez git-sizer –version. Si vous voyez une sortie comme git-sizer release 1.5.0, l’installation a réussi.
3. Installez jq. Pour plus d’informations, consultez Télécharger jq dans la documentation de jq.
4. Pour vérifier que jq est installé, exécutez jq –-version. Si vous voyez une sortie comme jq-1.6, l’installation a réussi.

Mesure de la taille des dépôts avec git-sizer

1. Pour cloner votre dépôt à partir de l’origine de migration, exécutez git clone --mirror.
2. Accédez au répertoire dans lequel vous avez cloné votre dépôt.
3. Pour obtenir la taille du plus gros fichier de votre dépôt en octets, exécutez git-sizer --no-progress -j | jq ".max_blob_size".
4. Pour obtenir la taille totale de tous les fichiers de votre dépôt en octets, exécutez git-sizer --no-progress -j | jq ".unique_blob_size".
5. Ajoutez les valeurs des étapes précédentes à votre inventaire.

À propos des types de migration

Lors de l’exécution d’une migration, vous pouvez choisir entre trois approches qui fournissent différents niveaux de fidélité de migration.

Type de migration	Définition	Configuration requise
Instantané de la source	Migre l’état actuel de votre code, tel qu’il est aujourd’hui, mais n’inclut aucun historique des révisions.	Possible pour chaque origine et chaque destination, même si votre code n’est pas suivi dans un système de gestion de versions.
Source et historique	Migre l’état actuel de votre code et son historique de révisions.	Possible si vous avez suivi vos modifications dans Git, ou un système de gestion de versions qui peut être converti en Git avant la migration.
Source, historique et métadonnées	Migre l’état actuel de votre code et de son historique de révisions, ainsi que votre historique de collaborations, tels que les problèmes et les demandes de tirage, et les paramètres.	Nécessite des outils spécialisés, qui ne sont pas disponibles pour tous les chemins de migration.

Lorsque vous décidez du type de migration à effectuer, tenez compte des besoins de votre organisation et des outils disponibles.

Vous pouvez utiliser différentes stratégies pour différents dépôts. Par exemple, vous pouvez avoir d’anciens dépôts archivés où l’historique n’est pas important, tandis qu’une migration haute-fidélité est indispensable pour votre code le plus actif.

À propos de nos différents modèles de prise en charge de migration

Vous pouvez choisir d’effectuer une « migration en libre-service », où vous planifiez et exécutez votre propre migration en utilisant seulement notre documentation, sans aucun support professionnel de GitHub.

Vous pouvez également préférer travailler avec l’équipe des Services d’experts de GitHub ou un partenaire GitHub, que nous appelons une « migration dirigée par un expert ». Avec une migration dirigée par un expert, vous bénéficiez des connaissances et de l’expérience d’un expert qui a déjà exécuté des dizaines, voire des centaines de migrations, et vous avez accès à des outils de migration supplémentaires qui ne sont pas disponibles en libre-service.

Pour en savoir plus sur les migrations dirigées par un expert, contactez votre représentant de compte ou les Services d’experts.

Choix des outils à utiliser

Pour planifier votre migration, prenez en compte la destination et la source. Ces considérations déterminent le chemin d’accès de votre migration. Pour plus d’informations, consultez « Chemins de migration vers GitHub ».

Conception de la structure de votre organisation pour la destination de migration

Dans GitHub, chaque dépôt appartient à une organisation. Les organisations sont des comptes partagés dans lesquels des entreprises et des projets open source peuvent collaborer sur de nombreux projets à la fois, avec des fonctionnalités sophistiquées de sécurité et d’administration. Pour plus d’informations, consultez « À propos des organisations ».

Que vous adoptiez GitHub pour la première fois ou que vous utilisiez déjà GitHub, prenez le temps de réfléchir à la structure la plus efficace pour vos organisations et dépôts après votre migration. La conception que vous choisissez peut optimiser la collaboration et la découverte et réduire la charge administrative, ou elle peut créer des silos et des surcharges administratives inutiles.

Nous vous recommandons de réduire le nombre d’organisations et de les structurer selon l’un des cinq archétypes. Pour des instructions détaillées, consultez « Meilleures pratiques pour structurer les organisations de votre entreprise ».

Exécution d’une migration test pour chaque dépôt

Avant de continuer la planification, effectuez une migration test incluant tous vos dépôts. Les exécutions test complètes vous permettent de :

• Vérifier que l’outil que vous avez choisi fonctionne pour vos dépôts
• Confirmer que l’outil répond à vos besoins
• Comprendre exactement quelles données sont migrées et quelles données ne le sont pas
• Comprendre combien de temps va durer votre migration pour vous aider à planifier votre migration de production

Il n’y a rien d’exceptionnel dans une migration test. Exécutez simplement une migration normale, puis supprimez le dépôt dans la destination de migration.

Planification de vos étapes de pré-migration et de post-migration

La migration de vos dépôts n’est qu’une étape d’un processus de migration plus vaste. Vous devrez effectuer d’autres étapes et éventuellement migrer des données ou des paramètres manuellement.

La liste complète des étapes requises pour votre migration dépend de votre situation unique, mais certaines étapes de pré-migration s’appliquent à toutes les migrations :

• Informer vos utilisateurs à l’avance de la migration à venir et de sa chronologie
• Envoyer des rappels peu avant le début de la migration
• Configurer des comptes d’utilisateur dans GitHub pour votre équipe
• Envoyer des instructions à vos utilisateurs pour mettre à jour leurs dépôts locaux afin qu’ils pointent vers votre nouveau système

Il existe également des étapes de post-migration qui s’appliquent à toutes les migrations :

• Informer vos utilisateurs que la migration est terminée
• Lier l’activité des utilisateurs dans votre destination de migration
• Désactiver l’origine de votre migration

Voici quelques autres étapes à prendre en compte lors de la planification de votre migration.

Migration de l’intégration continue (CI) et de la livraison continue (CD)

Si vous passez d’un produit GitHub à un autre, que vous utilisez déjà GitHub Actions pour CI/CD et que vous continuez à utiliser GitHub Actions, il n’y a pas grand-chose à faire. Les fichiers de workflow de vos dépôts seront automatiquement migrés pour vous. Si vous utilisez des exécuteurs auto-hébergés, vous devez les configurer dans votre nouvelle organisation GitHub afin qu’ils soient prêts à exécuter vos workflows.

Si vous n’utilisez pas GitHub Actions, la situation est plus compliquée. Si vous envisagez de continuer à utiliser le même fournisseur CI/CD, vous devez vérifier que le fournisseur est compatible avec GitHub et connecter le fournisseur à votre nouvelle organisation et à vos nouveaux dépôts.

Si vous envisagez de passer à GitHub Actions, nous vous déconseillons de le faire en même temps que la migration de vos dépôts. Attendez plutôt une date ultérieure et effectuez votre migration CI/CD en tant qu’étape distincte. Le processus de migration sera ainsi plus gérable. Lorsque vous êtes prêt à effectuer la migration, consultez « Migration vers GitHub Actions ».

Migration des intégrations

Vous utilisez probablement des intégrations avec votre fournisseur d’hébergement de code, développées en interne ou fournies par d’autres fournisseurs.

Si vous utilisez déjà GitHub, vous devez reconfigurer vos intégrations pour qu’elles pointent vers vos nouvelles organisations et vos nouveaux dépôts. Si l’intégration est fournie par un fournisseur, contactez celui-ci pour obtenir des instructions. Si l’intégration a été développée en interne, reconfigurez l’intégration dans votre nouvelle organisation, en générant de nouveaux jetons et de nouvelles clés.

Si vous débutez avec GitHub, vérifiez si vos intégrations sont compatibles avec GitHub, puis reconfigurez-les. Si vous utilisez des intégrations développées en interne, réécrivez-les pour qu’elles fonctionnent avec l’API GitHub. Pour plus d’informations, consultez « Documentation sur l’API REST GitHub ».

Liaison de l’activité des utilisateurs dans votre destination de migration

Si vous migrez l’historique de collaborations, ou les métadonnées, ainsi que le code, vous devez lier l’activité des utilisateurs à leurs nouvelles identités dans votre destination de migration.

Par exemple, supposons que @octocat a créé un problème sur votre instance GitHub Enterprise Server et que vous passez à GitHub Enterprise Cloud. Dans GitHub Enterprise Cloud, @octocat peut avoir un nom d’utilisateur complètement différent. Le processus d’attribution vous permet de lier l’activité utilisateur à ces nouvelles identités.

L’attribution fonctionne différemment d’un outil à l’autre :

• Si vous utilisez ghe-migrator, gl-exporter ou bbs-exporter, vous décidez de la façon dont vous souhaitez attribuer les données à l’avance et incluez un fichier de correspondances lorsque vous importez vos données.
• Si vous utilisez GitHub Enterprise Importer, les données sont liées à des identités d’espace réservé appelées « mannequins », et vous pouvez attribuer cet historique aux vrais utilisateurs une fois vos données migrées. Pour plus d’informations, consultez « Récupération de mannequins pour GitHub Enterprise Importer ».

Gestion des équipes et des autorisations

La plupart des clients utilisent des équipes pour gérer l’accès aux dépôts. Avec les équipes, au lieu de donner directement à Mona l’accès à un dépôt, vous pouvez ajouter Mona à l’équipe des ingénieurs et donner à tous les membres de l’équipe des ingénieurs l’accès au dépôt. Pour plus d’informations, consultez « À propos des équipes ».

Vous pouvez créer vos équipes et ajouter des membres d’équipe avant de migrer vos dépôts. Vous souhaiterez peut-être gérer vos membres via votre fournisseur d’identité (IdP) en liant vos équipes aux groupes d’idP. Pour plus d’informations, consultez « Synchronisation d’une équipe avec un groupe de fournisseurs d’identité ».

Toutefois, vous ne pouvez pas attacher vos équipes aux dépôts tant que vous n’avez pas migré les dépôts.