Plan your migration from GitLab to GitHub

Plan your migration by understanding your timeline, what data will be migrated, and your organizational structure.

Run your migration

Article 2 of 7
Next:Manage access for a migration from GitLab to GitHub

In this article

Determine how much you have to migrate

Figure out your timeline first, since it will largely shape your approach. The first step for determining your timeline is to get an inventory of what you need to migrate.

  • Number of repositories (projects)
  • Number of merge requests

Note

Migration timing is largely based on the number of merge requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 merge requests on average, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 merge requests on average, the migration will take much longer and require more planning and testing.

We recommend the inventory-report command in the GL2GH extension of the GitHub CLI. This command connects to the GitLab API and creates two CSV files. groups.csv lists your GitLab groups, and projects.csv lists your projects, including the number of merge requests.

To produce the CSV files, use the following command, replacing GITLAB_SERVER_URL with the URL of your GitLab server (for example, https://gitlab.com) and YOUR_GITLAB_GROUP with the group you want to report on. To report on all projects you can access, omit --gitlab-group. For all available options, run gh gl2gh inventory-report --help.

Shell
gh gl2gh inventory-report --gitlab-server-url GITLAB_SERVER_URL --gitlab-group YOUR_GITLAB_GROUP

After you take inventory of the repositories you need to migrate, weigh your inventory data against your desired timeline.

  • If your organization can withstand a higher degree of change, then you might be able to migrate all your repositories at once, completing your migration efforts in a few days.
  • If you have teams that are not able to migrate at the same time, you might want to batch and stagger your migrations to fit the teams' timelines, extending your migration effort.

Determine GitHub organizational structure

Next, plan the organizational structure you'll create in GitHub. GitLab and GitHub have different ways of organizing an enterprise's work.

  • GitLab: instance > groups > subgroups (which can be nested up to 20 levels deep) > projects (repositories)
  • GitHub: enterprise > organization > repositories

After migrating to GitHub, you should have only one enterprise account and a number of organizations owned by that enterprise. Each top-level group from GitLab typically corresponds to a single organization on GitHub. For guidance on how many organizations to create, see Best practices for organizing work in your enterprise.

Note

GitHub does not have an equivalent of GitLab's nested subgroups. We do not recommend creating an organization on GitHub for each subgroup, as this may result in a large list of ungrouped repositories within each organization. Instead, you can manage access to groups of repositories by creating teams.

If you want to break your migration effort into batches, the new structure can help you determine them. If you have more than one group in GitLab, and each group's repositories are reasonably sized batches, consider batching by group.

  1. Decide what your new organization structure will be.
  2. Decide if you need to break up your migration effort into smaller batches.
  3. If so, decide how you want to break up your migrations.

Configuring repository permissions

Because permissions work differently in GitHub than in GitLab, GitHub Enterprise Importer does not migrate repository permissions, group settings, or group membership from GitLab.

In GitLab, members are granted roles (such as Guest, Reporter, Developer, Maintainer, or Owner) at the group, subgroup, or project level, and these roles are inherited down the hierarchy. These roles do not map directly to GitHub, so you'll need to recreate access after migrating.

To give people access to migrated repositories on GitHub, we recommend creating teams and granting each team the appropriate level of access to the relevant organizations and repositories. You can then add people to those teams. See Teams in an enterprise.