Cross-Platform Git Migration

What you will learn

• Understand the core purpose of Cross-Platform Git Migration
• Master the basic usage and common options of Cross-Platform Git Migration
• Migrate repositories between GitHub, GitLab, Bitbucket, and other Git hosting platforms while preserving full commit history and all refs.
• Understand key concepts: Overview
• Know when to use this feature and when to avoid it

Start with a problem

Your team is migrating from another version control system to Git, or moving code and history between different Git platforms. You're worried about losing commit history or author information during the process.

Overview

Migrating between Git hosting platforms is straightforward at the Git level — the underlying protocol is the same. The key is transferring all refs (branches, tags, PR/MR metadata).

Core Migration Methods

Method 1: Bare Mirror (Recommended)

# 1. Create a mirror clone from the source
git clone --mirror https://github.com/old-org/repo.git
cd repo.git

# 2. Push to the target platform
git remote set-url origin https://gitlab.com/new-org/repo.git
git push --mirror origin

# 3. Verify
git log --oneline --all

--mirror clones all refs including branches, tags, and notes — the most complete transfer.

Method 2: Direct Push

# If you already have a full local clone
git remote add new-origin https://gitlab.com/new-org/repo.git
git push --all new-origin       # All branches
git push --tags new-origin      # All tags

Method 3: Multi-Platform Sync (Ongoing)

# Configure multiple remotes
git remote add github https://github.com/org/repo.git
git remote add gitlab https://gitlab.com/org/repo.git
git remote add bitbucket https://bitbucket.org/org/repo.git

# Push to all remotes
git push --all github
git push --all gitlab
git push --all bitbucket

Migrating PRs / Merge Requests

PRs/MRs are platform-level metadata, not Git objects — they can't be transferred with git push --mirror.

GitHub → GitHub

# Use GitHub's official migration tool
gh repo migrate <source-repo> --target-owner <target-org>

GitHub → GitLab

1. Create a new project in GitLab
2. Select Import project → GitHub
3. Authorize GitLab to access GitHub
4. Choose the repository to import

GitLab → GitHub

1. Click + → Import repository on GitHub
2. Enter the GitLab repo's Git URL
3. GitHub imports the history automatically

Metadata Migration Map

Post-Migration Checklist

# 1. Verify ref integrity
git for-each-ref --format='%(refname)' | sort

# 2. Check key branches
git branch -a

# 3. Verify tags
git tag -l

# 4. Confirm remote association
git remote -v

Try it yourself

1. Practice the platform-migration command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Continue Learning

1. migration/svn-to-git — SVN to Git migration
2. migration/hg-to-git — Mercurial to Git migration
3. hosting/platform-comparison — Platform comparison

Further reading

Keep going on the same topic:

• Mercurial to Git Migration Guide
• Repository Migration Strategy Guide
• SVN to Git Migration Guide