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 aidera à planifier et à exécuter 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 référentiels de code source et collaborer, tels que 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 contrôle de version 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	Le produit GitHub vers lequel vous migrez.
Chemin de migration	Combinaison de votre origine de migration et de votre destination de migration, par exemple « Bitbucket Server to GitHub Enterprise Cloud». Pour certains chemins de migration, GitHub propose des outils spécialisés, tels que GitHub Enterprise Importer, pour vous aider à migrer.

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, tel que GitHub.com ou GitHub Enterprise Server, ou il peut s’agir d’une autre plateforme d’hébergement de code, telle que 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.

Peu importe où se trouve votre code, c’est votre « origine de migration ».

Vous devez également connaître le produit vers lequel GitHub vous migrez ou vers votre « destination de migration ». Cela peut être GitHub.com, GHE.comou GitHub Enterprise Server.

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

Après avoir identifié l'origine et la destination de votre migration, déterminez les données dont vous avez besoin de migrer.

Vous devez créer un inventaire de migration avec une liste de tous les dépôts de sa ou ses sources de migration à transférer. 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 : in GitHub, il s’agirait d’une organisation, mais dans d’autres outils, il peut y avoir un autre type de propriétaire
• URL
• Horodatage de la dernière mise à jour
• Nombre de pull requests (ou équivalent dans votre origine de migration)
• Nombre de problèmes (ou équivalent dans votre origine de migration)

Si vous effectuez une migration depuis GitHub Enterprise Cloud ou GitHub Enterprise Server, vous pouvez obtenir ces données avec l’extension gh-repo-stats pour le 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 migrez à partir de Bitbucket Server ou du Centre de données Bitbucket, nous vous recommandons la inventory-report commande dans le 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 comment installer le 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	Exigences
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 collaboration, tels que les problèmes, les pull requests, 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 à l’aide de notre documentation uniquement, sans aucune prise en charge professionnelle de GitHub.

Vous pouvez également préférer travailler avec GitHubl’équipe Experts Services ou un GitHub partenaire, que nous appelons une « migration dirigée par des experts ». 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.

Si vous migrez une grande quantité de données, vous avez toutes les chances de bénéficier d'une migration menée par un expert. Par exemple, si vous migrez des milliers de référentiels, ou si vous avez des référentiels complexes d'une taille supérieure à 5 Go, nous vous recommandons de faire appel aux services d'experts.

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 [AUTOTITLE](/migrations/overview/migration-paths-to-github).

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

Dans GitHub, chaque référentiel 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 GitHubdéjà, suspendez pour prendre en compte la structure la plus efficace pour vos organisations et référentiels 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 organiser le travail dans 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
• Configurez 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
• Mettre hors service 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 entre les produits GitHub, utilisez déjà GitHub Actions pour CI/CD et continuerez à 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 GitHub organisation afin qu’elles soient prêtes à exécuter vos flux de travail.

Si vous n’utilisez GitHub Actionspas, 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 référentiels.

Si vous envisagez de basculer vers GitHub Actions, nous vous déconseillons de le faire en même temps que vous migrez 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(e) à 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 GitHubdéjà, vous devez reconfigurer vos intégrations pour qu’elles pointent vers vos nouvelles organisations et 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 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 utiliser l’API GitHub . Pour plus d’informations, consultez « documentation de 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 vous ayez @octocat 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 ou Enterprise Live Migrations, les données seront liées à des identités d’espace réservé appelées « mannequins », et vous pourrez affecter cet historique aux utilisateurs réels une fois vos données migrées. Pour plus d’informations, consultez « Récupération de modèles 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 d'organisation ».

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.