Article version: Enterprise Server 2.15

This version of GitHub Enterprise will be discontinued on This version of GitHub Enterprise was discontinued on 2019-10-16. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Resolving migration conflicts or setting up custom mappings

Before importing migration data, you can make corrections to resolve conflicts, rename incoming records, or map incoming records to existing records.

The following steps can be used to resolve conflicts or add custom mappings to your migration.

Resolving conflicts

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

For example, let's say you notice that the octocat user from the source is being mapped to octocat on the target:

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

You can choose to map the user to a different user on the target. Suppose you know that octocat should actually be monalisa on the target. You can change the target_url column in conflicts.csv to refer to monalisa:

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

As another example, if you want to rename the octo-org/widgets repository to octo-org/amazing-widgets on the target instance, change the target_url to octo-org/amazing-widgets and the recommend_action to rename:

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

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 the ghe-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 have map or rename as appropriate.

For example, to rename the user octocat to monalisa on the target https://example-gh.target you would create a row with the following content:

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

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

Applying modified migration data

  1. After making changes, use the scp command to apply your modified conflicts.csv (or any other mapping csv 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 the ghe-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 the ghe-migrator map -i conflicts.csv -g MIGRATION_GUID command reports that conflicts still exist, run through the migration conflict resolution process again.

Ask a human

Can't find what you're looking for?

Contact us