Migration de données vers GitHub Enterprise Server

Préparation des données migrées

1. À l’aide de la commande scp, copiez l’archive de migration générée à partir de votre organisation ou instance source vers votre cible GitHub Enterprise Server :

   scp -P 122 PATH-TO-MIGRATION-GUID.tar.gz admin@HOSTNAME:/home/admin/
   

2. Connectez-vous avec SSH à votre instance GitHub Enterprise Server cible. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

   ssh -p 122 admin@HOSTNAME
   

3. Utilisez la commande ghe-migrator prepare pour préparer l’archive à l’importation sur l’instance cible et générer un nouveau GUID de migration à utiliser dans les étapes suivantes :

   ghe-migrator prepare /home/admin/MIGRATION-GUID.tar.gz
   

   • Pour démarrer une nouvelle tentative d’importation, réexécutez ghe-migrator prepare et récupérez un nouveau GUID de migration.
   • Pour spécifier où ranger les fichiers de migration, ajoutez --staging-path=/full/staging/path à la commande. La valeur par défaut est /data/user/tmp.

Génération d’une liste des conflits de migration

1. À l’aide de la commande ghe-migrator conflicts avec le GUID de migration, générez un fichier conflicts.csv :

   ghe-migrator conflicts -g MIGRATION-GUID > conflicts.csv
   

   • Si aucun conflit n’est signalé, vous pouvez importer les données en toute sécurité.

2. En présence de conflits, à l’aide de la commande scp, copiez conflicts.csv sur votre ordinateur local :

   scp -P 122 admin@HOSTNAME:conflicts.csv ~/Desktop
   

3. Passez à la section « Résolution des conflits de migration ou configuration de mappages personnalisés ».

Examen des conflits de migration

1. À l’aide d’un éditeur de texte ou d’un tableur compatible CSV, ouvrez conflicts.csv.
2. En vous appuyant sur les exemples et tableaux de référence ci-dessous, consultez le fichier conflicts.csv pour vous assurer que les actions appropriées seront effectuées à l’importation.

Le fichier conflicts.csv inclut un mappage de migration avec les conflits et actions recommandées. Un mappage de migration liste les données migrées à partir de la source et la façon dont les données seront appliquées à la cible.

model_name	source_url	target_url	recommended_action
user	https://example-gh.source/octocat	https://example-gh.target/octocat	map
organization	https://example-gh.source/octo-org	https://example-gh.target/octo-org	map
repository	https://example-gh.source/octo-org/widgets	https://example-gh.target/octo-org/widgets	rename
team	https://example-gh.source/orgs/octo-org/teams/admins	https://example-gh.target/orgs/octo-org/teams/admins	merge
project	https://example-gh.source/octo-org/widgets/projects/1	https://example-gh.target/octo-org/projects/1	merge

Chaque ligne du fichier conflicts.csv fournit les informations suivantes :

Nom	Description
model_name	Le type de données modifiées
source_url	L’URL source des données
target_url	L’URL cible attendue des données
recommended_action	L’action que la commande ghe-migrator effectuera par défaut à l’importation des données

Mappages possibles pour chaque type d’enregistrement

La commande ghe-migrator peut effectuer différentes actions de mappage dans le cadre du transfert de données :

action	Description	Modèles applicables
import	(par défaut) Les données de la source sont importées dans la cible.	Tous les types d’enregistrement
map	Au lieu de créer un modèle basé sur les données sources, un enregistrement existant dans la cible est utilisé. Utile pour importer un référentiel dans une organisation existante ou pour mapper des identités utilisateur dans la cible aux identités utilisateur dans la source.	Utilisateurs, organisations, projets
rename	Les données de la source sont renommées, puis copiées sur la cible.	Utilisateurs, organisations, référentiels, projets
map_or_rename	Si la cible existe, le mappage est effectué avec cette cible. Sinon, le modèle importé est renommé.	Utilisateurs
merge	Les données de la source sont combinées avec les données existantes sur la cible.	Équipes, projets

Nous vous recommandons vivement de consulter le fichier conflicts.csv et d’utiliser ghe-migrator audit pour vous assurer que les actions appropriées seront effectuées. Si tout semble bon, vous pouvez continuer.

Résolution des conflits de migration ou configuration de mappages personnalisés

Si vous pensez que la commande ghe-migrator effectuera une modification incorrecte, vous pouvez apporter des corrections en modifiant les données dans conflicts.csv. Vous pouvez apporter des modifications à n’importe quelle ligne de conflicts.csv.

Par exemple, supposons que l’utilisateur octocat de la source soit mappé à octocat sur la cible.

model_name	source_url	target_url	recommended_action
user	https://example-gh.source/octocat	https://example-gh.target/octocat	map

Vous pouvez choisir de mapper l’utilisateur à un autre utilisateur sur la cible. Supposons que vous savez que octocat devrait être monalisa sur la cible. Vous pouvez changer la colonne target_url de conflicts.csv pour faire référence à monalisa.

model_name	source_url	target_url	recommended_action
user	https://example-gh.source/octocat	https://example-gh.target/monalisa	map

Autre exemple : si vous souhaitez renommer le dépôt octo-org/widgets en lui attribuant le nom octo-org/amazing-widgets sur l’instance cible, indiquez octo-org/amazing-widgets sous target_url et rename sous recommend_action.

model_name	source_url	target_url	recommended_action
repository	https://example-gh.source/octo-org/widgets	https://example-gh.target/octo-org/amazing-widgets	rename

Ajout de mappages personnalisés

Un scénario courant durant une migration consiste à changer les noms des utilisateurs migrés entre la source et la cible.

Avec une liste des noms d’utilisateur de la source et une liste de noms d’utilisateur sur la cible, vous pouvez créer un fichier CSV avec des mappages personnalisés, puis l’appliquer pour vous assurer que le nom et le contenu de chaque utilisateur lui sont correctement attribués à la fin d’une migration.

Vous pouvez rapidement générer un fichier des utilisateurs migrés au format CSV nécessaire pour appliquer des mappages personnalisés à l’aide de la commande ghe-migrator audit :

ghe-migrator audit -m user -g MIGRATION-GUID > users.csv

À présent, vous pouvez modifier ce fichier CSV et entrer la nouvelle URL pour chaque utilisateur à mapper ou renommer, puis mettre à jour la quatrième colonne pour qu’elle ait l’état approprié, map ou rename.

Par exemple, pour renommer l’utilisateur octocat avec le nom monalisa sur la cible https://example-gh.target, vous devez créer une ligne avec le contenu suivant :

model_name	source_url	target_url	state
user	https://example-gh.source/octocat	https://example-gh.target/monalisa	rename

Vous pouvez utiliser le même processus pour créer des mappages pour chaque enregistrement qui prend en charge les mappages personnalisés. Pour plus d’informations, consultez notre tableau des mappages possibles pour les enregistrements.

Application des données de migration modifiées

1. Après avoir apporté des modifications, utilisez la commande scp pour appliquer votre fichier conflicts.csv modifié (ou tout autre fichier .csv de mappage au format correct) à l’instance cible :

   scp -P 122 ~/Desktop/conflicts.csv admin@HOSTNAME:/home/admin/
   

2. Remappez les données de migration à l’aide de la commande ghe-migrator map en passant le chemin de votre fichier .csv modifié et le GUID de migration :

   ghe-migrator map -i conflicts.csv  -g MIGRATION-GUID
   

3. Si la commande ghe-migrator map -i conflicts.csv -g MIGRATION-GUID signale que des conflits sont toujours présents, reprenez le processus de résolution des conflits de migration.

Application des données importées sur GitHub Enterprise Server

1. Connectez-vous avec SSH à votre instance GitHub Enterprise Server cible. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

   ssh -p 122 admin@HOSTNAME
   

2. À l’aide de la commande ghe-migrator import, démarrez le processus d’importation. Vous devez disposer des éléments suivants :

   • Votre GUID de migration. Pour plus d’informations, consultez « Préparation des données migrées pour l’importation vers GitHub Enterprise Server ».
   • Votre personal access token pour l’authentification. Le personal access token que vous utilisez est uniquement destiné à l’authentification en tant qu’administrateur de site et ne nécessite pas d’étendue ou d’autorisation en particulier. Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels ».

   $ ghe-migrator import /home/admin/MIGRATION-GUID.tar.gz -g MIGRATION-GUID -u USERNAME -p TOKEN
   
   > Starting GitHub::Migrator
   > Import 100% complete /
   

   • Pour spécifier où ranger les fichiers de migration, ajoutez --staging-path=/full/staging/path à la commande. La valeur par défaut est /data/user/tmp.

Examen des données de migration

Par défaut, ghe-migrator audit retourne chaque enregistrement. Il vous permet également de filtrer les enregistrements par :

• les types d’enregistrements ;
• l’état des enregistrements.

Les types d’enregistrements correspondent à ceux trouvés dans les données migrées.

Filtres de types d’enregistrement

Type d’enregistrement	Nom du filtre
Utilisateurs	user
Organisations	organization
Référentiels	repository
Teams	team
Étapes majeures	milestone
Projets (classique)	project
Problèmes	issue
Commentaires de problème	issue_comment
Demandes de tirage	pull_request
Revues de demande de tirage	pull_request_review
Commentaires de commit	commit_comment
Commentaires de revues de demande de tirage	pull_request_review_comment
Versions	release
Actions effectuées sur les demandes de tirage ou les problèmes	issue_event
Branches protégées	protected_branch

Filtres d’états d’enregistrement

État d’enregistrement	Description
export	L’enregistrement sera exporté.
import	L’enregistrement sera importé.
map	L’enregistrement sera mappé.
rename	L’enregistrement sera renommé.
merge	L’enregistrement sera fusionné.
exported	L’enregistrement a été exporté avec succès.
imported	L’enregistrement a été importé avec succès.
mapped	L’enregistrement a été mappé avec succès.
renamed	L’enregistrement a été renommé avec succès.
merged	L’enregistrement a été fusionné avec succès.
failed_export	L’enregistrement n’a pas pu être exporté.
failed_import	L’enregistrement n’a pas pu être importé.
failed_map	L’enregistrement n’a pas pu être mappé.
failed_rename	L’enregistrement n’a pas pu être renommé.
failed_merge	L’enregistrement n’a pas pu être fusionné.

Filtrage des enregistrements audités

Avec la commande ghe-migrator audit, vous pouvez filtrer en fonction du type d’enregistrement à l’aide de l’indicateur -m. De même, vous pouvez filtrer sur l’état d’importation à l’aide de l’indicateur -s. La commande se présente comme suit :

ghe-migrator audit -m RECORD_TYPE -s STATE -g MIGRATION-GUID

Par exemple, pour afficher toutes les organisations et équipes importées avec succès, vous pouvez entrer :

$ ghe-migrator audit -m organization,team -s mapped,renamed -g MIGRATION-GUID
> model_name,source_url,target_url,state
> organization,https://gh.source/octo-org/,https://ghe.target/octo-org/,renamed

Nous vous recommandons vivement d’auditer chaque importation qui a échoué. Pour ce faire, vous devez entrer :

$ ghe-migrator audit -s failed_import,failed_map,failed_rename,failed_merge -g MIGRATION-GUID
> model_name,source_url,target_url,state
> user,https://gh.source/octocat,https://gh.target/octocat,failed
> repository,https://gh.source/octo-org/octo-project,https://ghe.target/octo-org/octo-project,failed

Si vous avez des préoccupations concernant les importations ayant échoué, vous pouvez nous contacter en visitant Support GitHub Enterprise.

Fin de l’importation sur GitHub Enterprise Server

Une fois que votre migration a été appliquée à votre instance cible et que vous avez passé en revue la migration, vous pouvez déverrouiller les dépôts et les supprimer de la source. Avant de supprimer vos données sources, nous vous recommandons d’attendre environ deux semaines pour vous assurer que tout fonctionne comme prévu.

Déverrouillage des dépôts sur l’instance cible

1. Connexion SSH à GitHub.com. Si votre instance comprend plusieurs nœuds, par exemple si la haute disponibilité ou la géoréplication sont configurées, connectez-vous via SSH au nœud principal. Si vous utilisez un cluster, vous pouvez vous connecter via SSH à n’importe quel nœud. Remplacez HOSTNAME par le nom d’hôte de votre instance, le nom d’hôte ou l’adresse IP d’un nœud. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Déverrouillez tous les référentiels importés à l’aide de la commande ghe-migrator unlock. Vous aurez besoin de votre GUID de migration :

$ ghe-migrator unlock -g MIGRATION-GUID
> Unlocked octo-org/octo-project

Déverrouillage des dépôts sur la source

Une fois votre migration terminée, vous devez déverrouiller les dépôts sur la source.

Déverrouillage des dépôts d’une organisation sur GitHub.com

Pour déverrouiller les dépôts d’une organisation GitHub.com, vous devez envoyer une demande DELETE au point de terminaison de déverrouillage de migration. Vous devez disposer des éléments suivants :

• Votre jeton d’accès pour l’authentification
• L’id unique de la migration
• Le nom du dépôt à déverrouiller

curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" -X DELETE \
  -H "Accept: application/vnd.github.wyandotte-preview+json" \
  https://api.github.com/orgs/ORG-NAME/migrations/ID/repos/REPO_NAME/lock

Suppression de dépôts d’une organisation sur GitHub.com

Après avoir déverrouillé les dépôts de l’organisation GitHub.com, vous devez supprimer chaque dépôt que vous avez précédemment migré à l’aide du point de terminaison de suppression de dépôt. Vous avez besoin de votre jeton d’accès pour l’authentification :

curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" -X DELETE \
  https://api.github.com/repos/ORG-NAME/REPO_NAME

Déverrouillage des dépôts à partir d’une instance GitHub Enterprise Server

1. Connexion SSH à GitHub.com. Si votre instance comprend plusieurs nœuds, par exemple si la haute disponibilité ou la géoréplication sont configurées, connectez-vous via SSH au nœud principal. Si vous utilisez un cluster, vous pouvez vous connecter via SSH à n’importe quel nœud. Remplacez HOSTNAME par le nom d’hôte de votre instance, le nom d’hôte ou l’adresse IP d’un nœud. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Déverrouillez tous les référentiels importés à l’aide de la commande ghe-migrator unlock. Vous aurez besoin de votre GUID de migration :

$ ghe-migrator unlock -g MIGRATION-GUID
> Unlocked octo-org/octo-project