Preparing the migrated data

1. Using thescp command, copy the migration archive generated from your source instance or organization to your GitHub Enterprise Server target:

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

2. SSH into your target GitHub Enterprise Server instance. For more information, seeAccessing the administrative shell (SSH).

   ssh -p 122 admin@HOSTNAME

3. Ensure the migration archive has sufficient read permissions.

   chmod 644 /home/admin/MIGRATION-GUID.tar.gz

4. Use theghe-migrator prepare command to prepare the archive for import on the target instance and generate a new Migration GUID for you to use in subsequent steps:

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

   • To start a new import attempt, runghe-migrator prepare again and get a new Migration GUID.
   • To specify where migration files should be staged append the command with--staging-path=/full/staging/path. Defaults to/data/user/tmp.

Generating a list of migration conflicts

1. Using theghe-migrator conflicts command with the Migration GUID, generate aconflicts.csv file:

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

   • If no conflicts are reported, you can safely import the data.

2. If there are conflicts, using thescp command, copyconflicts.csv to your local computer:

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

3. Continue toResolving migration conflicts or setting up custom mappings.

Reviewing migration conflicts

1. Using a text editor orCSV-compatible spreadsheet software, openconflicts.csv.
2. With guidance from the examples and reference tables below, review theconflicts.csv file to ensure that the proper actions will be taken upon import.

Theconflicts.csv file contains amigration map of conflicts and recommended actions. A migration map lists out both what data is being migrated from the source, and how the data will be applied to the target.

Each row inconflicts.csv provides the following information:

Possible mappings for each record type

There are several different mapping actions thatghe-migrator can take when transferring data:

We strongly suggest you review theconflicts.csv file and useghe-migrator audit to ensure that the proper actions are being taken. If everything looks good, you can continue.

Resolving migration conflicts or setting up custom mappings

If you believe thatghe-migrator will perform an incorrect change, you can make corrections by changing the data inconflicts.csv. You can make changes to any of the rows inconflicts.csv.

For example, let's say you notice that theoctocat user from the source is being mapped tooctocat on the target.

You can choose to map the user to a different user on the target. Suppose you know thatoctocat should actually bemonalisa on the target. You can change thetarget_url column inconflicts.csv to refer tomonalisa.

As another example, if you want to rename theocto-org/widgets repository toocto-org/amazing-widgets on the target instance, change thetarget_url toocto-org/amazing-widgets and therecommend_action torename.

Adding custom mappings

A common scenario during a migration is for migrated users to have different usernames on the target than they have on the source.

Given a list of usernames from the source and a list of usernames on the target, you can build a CSV file with custom mappings and then apply it to ensure each user's username and content is correctly attributed to them at the end of a migration.

You can quickly generate a CSV of users being migrated in the CSV format needed to apply custom mappings by using theghe-migrator audit command:

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

Now, you can edit that CSV and enter the new URL for each user you would like to map or rename, and then update the fourth column to havemap orrename as appropriate.

For example, to rename the useroctocat tomonalisa on the targethttps://example-gh.target you would create a row with the following content:

The same process can be used to create mappings for each record that supports custom mappings. For more information, seeour table on the possible mappings for records.

Applying modified migration data

1. After making changes, use thescp command to apply your modifiedconflicts.csv (or any other mapping.csv file in the correct format) to the target instance:

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

2. Re-map the migration data using theghe-migrator map command, passing in the path to your modified.csv file and the Migration GUID:

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

3. If theghe-migrator map -i conflicts.csv -g MIGRATION-GUID command reports that conflicts still exist, run through the migration conflict resolution process again.

Applying the imported data on GitHub Enterprise Server

1. SSH into your target GitHub Enterprise Server instance. For more information, seeAccessing the administrative shell (SSH).

   ssh -p 122 admin@HOSTNAME

2. Using theghe-migrator import command, start the import process. You'll need:

   • Your Migration GUID. For more information, seePreparing the migrated data for import to GitHub Enterprise Server.
   • Your personal access token for authentication. The personal access token that you use is only for authentication as a site administrator, and does not require any specific scope or permissions. For more information, seeManaging your personal access tokens.

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

   • To specify where migration files should be staged append the command with--staging-path=/full/staging/path. Defaults to/data/user/tmp.

Reviewing migration data

By default,ghe-migrator audit returns every record. It also allows you to filter records by:

• The types of records.
• The state of the records.

The record types match those found in themigrated data.

Record type filters

Record state filters

Filtering audited records

With theghe-migrator audit command, you can filter based on the record type using the-m flag. Similarly, you can filter on the import state using the-s flag. The command looks like this:

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

For example, to view every successfully imported organization and team, you would enter:

$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

We strongly recommend auditing every import that failed. To do that, you will enter:

$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

If you have any concerns about failed imports, you can contact us by visitingGitHub Enterprise Support.

Completing the import on GitHub Enterprise Server

After your migration is applied to your target instance and you have reviewed the migration, you''ll unlock the repositories and delete them off the source. Before deleting your source data we recommend waiting around two weeks to ensure that everything is functioning as expected.

Unlocking repositories on the target instance

1. SSH into GitHub.com. If your instance comprises multiple nodes, for example if high availability or geo-replication are configured, SSH into the primary node. If you use a cluster, you can SSH into any node. Replace HOSTNAME with the hostname for your instance, or the hostname or IP address of a node. For more information, seeAccessing the administrative shell (SSH).

   Shell

   ssh -p 122 admin@HOSTNAME

2. Unlock all the imported repositories with theghe-migrator unlock command. You'll need your Migration GUID:

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

Unlocking repositories on the source

After your migration is complete, you should unlock the repositories on the source.

Unlocking repositories from an organization on GitHub.com

To unlock the repositories on a GitHub.com organization, you'll send aDELETE request tothe migration unlock endpoint. You'll need:

• Your access token for authentication
• The uniqueid of the migration
• The name of the repository to unlock

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

Deleting repositories from an organization on GitHub.com

After unlocking the GitHub.com organization's repositories, you should delete every repository you previously migrated usingthe repository delete endpoint. You'll need your access token for authentication:

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

Unlocking repositories from a GitHub Enterprise Server instance

1. SSH into GitHub.com. If your instance comprises multiple nodes, for example if high availability or geo-replication are configured, SSH into the primary node. If you use a cluster, you can SSH into any node. Replace HOSTNAME with the hostname for your instance, or the hostname or IP address of a node. For more information, seeAccessing the administrative shell (SSH).

   Shell

   ssh -p 122 admin@HOSTNAME

2. Unlock all the imported repositories with theghe-migrator unlock command. You'll need your Migration GUID:

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