Skip to content

Migration from GitLab Cloud

At GitLabHost, we have created internal tooling to perform a migration of your groups, projects and users hosted on the GitLab.com cloud to an instance hosted by GitLabHost.

This document lists known issues, caveats, requirements, and other details about the migration process, so you know what to expect from a migration process.

Important remarks

  • We use the built-in group and project export and import features of GitLab. These have known caveats, please read the Items that are exported list on GitLab.com

  • Email addresses on GitLab.com are not publicly readable, but we need to know the addresses for perform the migration. Please read the Email Addresses section for more information.

  • Before, during, and for a short amount of time after the migration, we disable all email sending on the target GitLab instance to prevent users from being bombarded with emails about project imports and permission assignment. This causes functionality such as password reset to not work during the migration.

  • We do not send out password reset emails for users we create during the migration. Users will have to manually perform a password reset after the migration, or sign up using SSO.

  • In addition to the items exported by GitLab by default, we also attempt to migrate users and their profiles. This includes public SSH and GPG keys that the user has set on their profile.

  • Two Factor Auth registrations are not migrated, and when 2FA is enforced in groups, users will have to manually re-register their 2FA integration. Users will be prompted for this when they first log in on the target instance.

Migration steps

  1. Please contact us about your migration, so we can plan the migration together.
  2. Ensure you have all requirements ready before the migration.
  3. We discover the groups, projects and users you currently have on GitLab.com to create an overview of data to migrate.
  4. We send you the list of usernames we discovered to complete the email address mapping.
  5. We schedule and then perform a (partial) test migration if you want one.
  6. You take a look around your new instance to double-check that the test migration is performed as required.
  7. We perform the full final migration.

Requirements

For us to perform a migration for you, you need to have the following things ready at the time of migration:

Email addresses

Email addresses on GitLab.com are not publicly readable, but we need to know the addresses for perform the migration.

During the discovery step of the migration, we create a list of usernames found on the source instance. We try to map email addresses that we can find, to the correct usernames where possible.

This is only possible when users have their email address set to public, or the user that already exists on the target instance.

If the list is incomplete, we will send you the complete list and request you to fill in the blanks. The list is formatted in toml format, and looks like this:

[users]
gitlabhost = "support@gitlabhost.com"   # Completed example
username = ""                           # Missing email
"user.with.dots" = ""                   # Missing email, quoted username for formatting

toml is a fairly standard format for configuration files, and you may be able to automate filling in the list if you have the required information stored in computer-readable format somewhere.

If the email address are predictable, for example, they are always username@companyname.com, we can auto-fill the list for you.

Alternatively, you can also have your users either sign up or invited to the target instance with the same username as on the source instance, so we can fetch the required information with the API on the target instance.

Last update: 2022-07-07