Complete Guide to Migrating Projects from GitHub to GitLab

Introduction

In software development, project migration is a common requirement, such as moving from GitHub to GitLab. This process involves not only the code repository but also the complete project history and various collaboration metadata. Based on GitLab official documentation and community practices, this guide offers a comprehensive migration approach to ensure all data—including commits, branches, tags, issues, pull requests, Wiki, milestones, labels, and comments—is successfully imported.

Pre-Migration Preparation

Before starting the migration, it is essential to ensure that GitHub users are correctly mapped to GitLab users. This can be achieved in two ways: either the GitLab account has logged in using the GitHub icon, or the GitLab account's email address matches the public email address of the GitHub user. This step is critical as it affects the ownership and accessibility of metadata like issues and comments. Incomplete user mapping may lead to data loss or permission issues.

Using GitLab Official Import Tool

GitLab provides a built-in GitHub import feature that simplifies the migration process. First, click the "+" button in the top navigation bar and select "New project." Then, in the Import project tab, choose "GitHub." The system will prompt you to authorize the GitLab application to access your GitHub account. After clicking "Authorize gitlabhq," you will be redirected back to GitLab's import page, where all your GitHub repositories are listed. Select the repositories to import, and GitLab will automatically handle the remaining steps, including downloading code and metadata.

This method supports the import of issues, pull requests, Wiki, milestones, labels, release notes, and comments. GitLab documentation emphasizes that the import process may vary based on repository size and network conditions, recommending operation during low-traffic periods to avoid timeouts. After import, verify all data for completeness and manually adjust user mappings if necessary.

Supplementary Method: Git Command Migration

If the official import tool is not suitable, such as in custom GitLab installations or when finer control is needed, Git commands can be used for migration. Start by creating a new local directory and using the git clone --mirror command to clone the GitHub repository, which copies all branches, tags, and commit history. For example: git clone --mirror https://github.com/raveren/kint. Enter the cloned directory and add the GitLab remote repository: git remote add gitlab http://gitlab.example.com/raveren/kint.git. Finally, use git push gitlab --mirror to push all references.

For existing local repositories, update the remote configuration: first remove the original remote with git remote remove origin, then add the new remote with git remote add origin http://gitlab.example.com/raveren/kint.git, and execute git fetch --all to synchronize data. This method is ideal for migrating only code and history, without involving GitHub-specific metadata like issues or Wiki.

Auxiliary Scenario: Local Git Repository Migration

Referenced articles discuss challenges in migrating local Git repositories to a GitLab installation, such as when the original Git server is disabled. In such cases, repositories can be moved directly via the file system. GitLab repositories are typically stored in the /var/opt/gitlab/git-data/repositories directory. Copy the local repository to this location and ensure correct permissions, possibly requiring re-indexing with GitLab's API or command-line tools. This approach requires system administrator privileges and carries higher risks, potentially disrupting existing configurations.

An alternative is to temporarily re-enable the original Git server's SSH service, but this necessitates disabling GitLab's SSH service first to avoid conflicts. Backup data before proceeding and refer to GitLab documentation for step-by-step adjustments. This method is suited for self-hosted environments, highlighting the importance of cautious system configuration during migration.

Best Practices and Considerations

Before migration, backup all data, including GitHub repositories and local copies. When using GitLab's import tool, pay attention to network stability and timeout settings. For large repositories, phased migration may be more reliable. After migration, verify the integrity of all branches, tags, and metadata, and test functionalities to ensure a smooth transition. If user mapping issues arise, manually adjust account settings in GitLab.

In code examples, special characters like <T> must be escaped to prevent HTML parsing errors. For instance, when describing tags, write <br> instead of using the tag directly to ensure proper text display. In summary, combining official tools and Git commands allows flexible handling of various migration needs, enhancing development efficiency.