Strategies for migrating from GitHub to GitLab

Ooh, that moment when you decide to move to GitLab ❤️

It's all great, until you realize there are all these loose ends you need to think about 🙈

  • will the git commit authors be kept correctly after the import?
  • can I migrate issues / pull requests ?
  • can I just stop the existing CI pipeline or do other teams / projects depend on it?

These are some of the things I've had to think about while recently migrating the project I am working on to GitLab.

Here's what I learned.

I found there are 3 approaches to the migration.

#1. Migrate everything at once

This means you would:

  • Start using the GitLab as hosted git repository instead of GitHub
  • Use GitLab as CI for your project
  • The previous GitHub project is closed

This is the most straightforward way to go and should be your first choice if possible 🚀.

#2. Migrate your CI pipeline first

This means you would:

  • Keep using GitHub as your hosted git repo
  • Use GitLab as CI for your GitHub repo

Why would you want to do this?

  • If there are external dependencies on your GitHub repo - e.g. Jenkins pipelines owned by other teams that can't/won't update them immediately
  • If you want to run both your "old" CI pipeline and the Gitlab one in parallel for a while, to make sure there are no regressions in how the artifacts are built
  • If you want to allow users to get used gradually to the GitLab ecosystem (i.e. not disrupt day to day work by switching cold turkey)

This might sound a bit like overkill, but for a bigger organisation with multiple teams and a more complex release process, this could make sense.

Once the other teams have also switched to GitLab, you can make the full switch and no longer use GitHub at all.

#3. Migrate fully but keep GitHub as a read-only mirror

This means you would:

  • Use GitLab as the hosted git repository
  • Use GitLab as CI
  • Keep the GitHub repo, but make it read-only

Why would you want to do this?

  • If you have an open source project and you want to keep the visibility that GitHub brings
  • If you want to migrate 100%, but still have external dependencies (as described in step #2) -> this option would bring the best of both worlds 💪

This is the option I wish I had thought of when I migrated my project 😀 I was too much "in the middle of it" that I only realised this could be an approach after I finished the migration with option #2.

What worked for you?

Did you go through a migration from GitHub to GitLab? How did you approach it?

Here are some things I learned while doing this: