This playbook is a step-by-step guide to assist you with migration from Gitlab to Github.com Enterprise Cloud GHEC.

For instance, Gitlab uses a different naming convention than Github for things, as quick reference use the table below to upgrade your Gitlab lingo into Github.

We're constantly evolving our tools to support new things, however the interoperability between Gitlab and Github, may lead some crumbs along the way, please check what you can and can't migrate using our tool.

• Check the limits of migrating data from Gitlab to Github using Gitlab Exporter tool.
• Make a list of all repositories that need to be migrated
• Categorize/Group the repositories depending on the different source platforms
• Create a source-to-target matrix/checklist for each of the categorized/grouped repositories
• Determine potential Organization that will be created in the target platform
• Check the scope of the migration to be executed

With all the checkboxes confirmed, let's move to the step 2.

Now the you did the ground work, it's time to prepare the data from Gitlab to Github, for instance, as a rule of thumb, try to use a simple Group from Gitlab with max 5 repositories, this will allow to understand mapping and adjust your requirements. We do recommend to consolidate into maximum of 2 organisations, because is easy to maintain and govern, however in some scenarios companies that are services provider they like to keep the same structure when migrating to Github.

• Preparing the file to be imported at Github
• Ask a Github Professional member to include the target organization and user account to use ECI tool.

With your archive ready to import, it's time to upload the file you prepared and valdiate the data using our ECI tool.

• Follow the steps described here to import the file package to GitHub Enterprise Cloud.
• Check the Gitlab caveats, which list some of the things you should be aware, in case you're having trouble.

• Migrations to GitHub Enterprise Cloud are scoped to a single organization.
• All incoming users must have an account on GitHub.com for user mapping purposes and will need to be invited to the importing GitHub Enterprise Cloud organization and accept their invitations.
• Users that do not have a matching GitHub.com account created and added as a member to the importing organization at the time of the migration will be mapped to a placeholder user.
• (If applicable) We recommend consolidating repositories and teams (if supported) on a single organization on the source export instance. This will frontload the work of resolving naming conflicts (duplicate repository and team names) and organizing teams for access control.
• Create an admin token on GitHub.com. Remember to discard once used

Note: - The user will authenticate with a very high authority using the Personal Access Token

• Select the admin:org scope
• If the user has not created PAT, follow instructions documented here
• Select Authenticate

If the system seems to hang during the import, you can run the following command to gather information on the migration process and see the models being migrated:

curl --request POST \
 --url https://api.github.com/graphql \
 -H 'authorization: Bearer TOKEN' \
-H'content-type: application/json' \
--header 'graphql-features: gh_migrator_import_to_dotcom' \
--data '{"query":"query(\n  $login: String!,\n  $guid: String!,\n){\n  organization(login: $login) {\n    migration(guid: $guid) {\n      state\n      guid\n      id\n      migratableResources(\n        first: 100\n\t\t\t\tstate: IMPORTED\n        \n      ) {\n        totalCount\n      }\n    }\n  }\n}","variables":{"login":"THE_ORG_NAME","guid":"THE_MIGRATION_GUID"}}'

• If you made a mistake and didn't name the repositories properly, they might end up been in a lock phase and you're unable to delete to restart the importing process, If that happens open a support ticket.

• GitHub.com Import page
• Post-migration checklist
• Github Enterprise Organisations and Teams
• Github Enterprise Administrators guidelines
• Github Markdown Syntax