Using the Git-Lab Exporter

Customers using GitLab.com, GitLab Enterprise Edition, or GitLab Community Edition can easily move their data to GitHub Enterprise using the new GitLab Exporter utility.

Date Created: 2016-01-10

Date Reviewed: YYYY-MM-DD

Affected products and versions:

• GitHub.com

• GitHub Enterprise (Versions: 2.6.3+ )

Index

• Prerequisites

• Steps

• Reference

• Further Reading

Prerequisites

GitHub Enterprise version

The migration utilities required for this migration were introduced in GitHub Enterprise 2.6.3. If your version of GitHub Enterprise is lower than 2.6.3, please upgrade your instance by following instructions at:

https://help.github.com/enterprise/admin/guides/installation/upgrading-the-github-enterprise-virtual-machine/

Note: Support for migrating webhooks and repository collaborators (team members) was introduced in GitHub Enterprise 2.7. If you need support for these models, please upgrade to GitHub Enterprise 2.7.

GitLab Version

The GitLab Exporter can be run against GitLab.com, or versions of GitLab EE and GitLab CE 8.9.0 or greater.

Backup utilities

When performing a migration, it is strongly recommended that you back up your GitHub Enterprise instance frequently. This affords flexibility in trying different migration strategies.

Instructions for downloading and installing GitHub's backup utilities can be found at:

https://github.com/github/backup-utils

Migration environment

A computer must be set up to perform the migration, and will have the GitLab Exporter utility installed. It must also have network access to GitLab, the GitHub Enterprise Sandbox, and GitHub Enterprise Production. Also, it must have the following prerequisites installed:

• Ruby 2.2.3: We suggest installing with RVM or rbenv

• An SSH client

• A cloned copy of GitLab Exporter (see below)

• Git 2.7 or greater

You can verify the dependencies are properly installed using the GitLab Exporter Preflight Script.

Access to GitLab Instance

When performing the migration, you will need SSH clone access to all projects you wish to export.

GitHub Enterprise sandbox environment

Since you will be performing trial runs of the migration before the actual production migration, it is necessary to have a recent backup snapshot of your GitHub Enterprise instance restored to a sandbox environment, so current users will not be affected by the trial runs. You may either opt to take a snapshot of the production virtual machine, or use GitHub's backup utilities to restore a recent backup to a fresh instance of GitHub Enterprise (running the same version as production).

Trial runs are migrations that import data to a staging instance. These can be useful to see what would happen if a migration were applied to your GitHub Enterprise instance. We strongly recommend that you perform a trial run on a staging instance before importing data to your production instance.

GitHub Enterprise access

When actually importing the repository data to GitHub Enterprise, you will need the following access to both the development and production environments:

• SSH access

• Ownership of the target organization on GitHub Enterprise

• Site admin access

Username mappings

If your GitHub Enterprise instance uses LDAP, or if it enforces username formatting requirements, you will need a mapping of GitLab usernames to GitHub Enterprise or LDAP usernames for your organization. Username mappings are also necessary for instances of GitHub Enterprise that already have users on them, when those users may have also contributed work to your repositories on GitLab. Please have ready a CSV file that connects the usernames between GitLab and GitHub Enterprise.

The format for the CSV file can be found in the GitHub Enterprise Guides.

Steps

The GitLab Exporter utility can be found at https://github.com/github/gl-exporter

Clone the utility with:

git clone https://github.com/github/gl-exporter.git

From within the GitLab Exporter source code directory, run the following command to install the utility and its Ruby dependencies.

$ script/bootstrap

Specify the following environment variables for the GitLab API endpoint and your GitLab private token.

$ export GITLAB_API_ENDPOINT=https://gitlab.example.com/api/v3
$ export GITLAB_API_PRIVATE_TOKEN=1234567890

Note: The GitLab Exporter only clones using SSH and will only use your default SSH key (typically ~/.ssh/id_rsa). You can specify a different key or port for your GitLab host using a SSH config file in ~/.ssh/config.

Exporting a single project

Create an export archive by passing the namespace and project name for your GitLab project. The -o flag specifies where to save the archive.

$ gl_exporter --namespace gitlab-org --project gitlab-ce -o migration_archive.tar.gz

Exporting multiple projects from a CSV

Prepare a CSV file with a namespace and project name on each line. For example:

export_list.csv

gitlab-org,gitlab-ce
group-name,project-name
some-user,some-project

Each project will be exported when the CSV is passed to the utility with the -f flag.

$ gl_exporter -f path/to/export_list.csv -o migration_archive.tar.gz

Locking the source project

In order to prevent commits from being made to the project after the export has begun, you can set the flag --lock-projects=true. You should do this during your production migration to ensure no updates are made to the GitLab projects that would not be imported to GitHub Enterprise.

Importing to GitHub Enterprise

Once the migration archive has been created, you can upload it to your GitHub Enterprise instance. From there, you can use the instructions for the ghe-migrator tools in the public "Importing migration data to GitHub Enterprise" guide.

Exported data

Model	Can Export?	Notes
Users	:white_check_mark:
Groups	:white_check_mark:	Imported as "Organizations"
Group Members	:white_check_mark:	Imported as "Teams"
Projects	:white_check_mark:	Imported as "Repositories"
Project Team Members	:white_check_mark:	Imported as "Repository Collaborators"; Requires GitHub Enterprise 2.7
Merge Requests	:white_check_mark:	Imported as "Pull Requests"; renumbered sequentially along with Issues
Merge Request Notes	:expressionless:	Imported as "Issue Comments"; GitLab does not provide enough data to determine diff notes, so all are imported inline
Issues	:white_check_mark:
Issue Notes	:white_check_mark:	Imported as "Issue Comments"
Events	:expressionless:	Events are imported as Issue Comments, since GitLab's API does not provide enough information to build robust Events in GitHub
Webhooks	:white_check_mark:	Requires GitHub Enterprise 2.7
Attachments	:white_check_mark:
Tags	:white_check_mark:	Imported as "Releases"
Avatars	:x:	Avatars are not supported by ghe-migrator and are not currently on the roadmap for the GitLab Exporter
Commit Comments	:white_check_mark:
Wikis	:white_check_mark:
Milestones	:white_check_mark:	Since GitLab Milestones can be assigned to multiple Projects, we duplicate the Milestone for all associated Repositories

Further reading

• GitHub Enterprise Migration Guides

• Migrating from GitHub.com to GitHub Enterprise