This playbook is a step-by-step guide to assist you with migration from GitLab to GitHub.com Enterprise Cloud GHEC.
| Steps & Tasks | Description |
|---|---|
| Step One | Let's get ready for the migration. This step gives you an overview of what is required to start the migration process |
| Step Two | Creating the artefact to be imported on GitHub requires special access to the Enterprise Cloud Import tool. This step will help you understand what is required to get access to the tool. |
| Step Three | With the file ready to be imported, this step will guide you on how to connect and upload the file to your GitHub Enterprise Cloud instance. |
For instance, GitLab uses a different naming convention than GitHub for things, as a quick reference, use the table below to upgrade your GitLab lingo into GitHub.
| GitLab | GitHub |
|---|---|
| Groups | Organizations |
| Group members | Teams |
| Projects | Repositories |
| Merge Requests | Pull Requests |
| Merge Request Notes | Issue comments |
| Issue notes | Issue comments |
We're constantly developing 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 Organizations that will be created in the target platform
- Check the scope of the migration to be executed
- Setup the Migration tool for GitLab.
With all the checkboxes confirmed, let's move to step two.
Now that you did the groundwork, 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 you to understand mapping and adjust your requirements. We do recommend to consolidate into a maximum of 2 Organizations, because is easy to maintain and govern, however in some scenarios companies that are services providers, they like to keep the same structure when migrating to GitHub.
- Preparing the file to be imported at GitHub
With your archive ready to import, it's time to upload the file you prepared and validate the data using our ECI tool.
- Ask a GitHub Professional member to include the target organization and user account to use 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 front-load 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:orgscope- 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"}}'There are a few err
- If you made a mistake and didn't name the repositories properly, they might end up being in a lock phase and you're unable to delete to restart the importing process. If that happens, open a support ticket witht Professional Services Architect assigned to your project.
- If you're having trouble with the migration, you can [open a support ticket]( with the Migration GUID and the error message) and we'll be able to help you.
- ECI tool is cannot handle large files, which may fail several times before the migration is complete, Try multiple times. If the problem persists, contact the Professional Services Architect assigned to your project.