Channel Partner Migration Services

GitLab encourages our GitLab Partners to engage in and lead technical services such as migrating to GitLab. This page overviews different data sources that can be transferred to various GitLab destinations. For deeper technical understanding, engineers should enroll and learn from the GitLab University GitLab Certified Migration Services Specialist Learning Path.

See Import and Migrate Groups and Projects for a short technical overview of available paths to importing or migrating to GitLab.

Common migration steps for GitLab Partners

For the links in this section, login to our GitLab Partner Portal first, then click the links:

GitLab Partners who are successful at performing customer-facing migrations often take this example path in client engagement:

1. Scope/size of the migration: How many users? How many code repositories? Will the group structure remain intact, or is the migration an opportunity to ‘clean up unused projects’ within GitLab? Would a GitLab Partner Led Optimization Service be a better first step?
2. Understand the customer’s business: What artifacts are needed to be migrated? Is an audit-compliance history of users, issues, and merge requests important to the company? Or is migrating just the git code repository sufficient? What data is your customer sensitive to migrating?
3. Health check: Is the import data source healthy, or would a Readiness Assessment help provide the health of the GitLab source? Are some git repositories unable to be cloned, or require cleaning up? Are there any large code repositories with a long-lived history?
4. Post-migration needs: Are there other consultative considerations like access control, and Single-Sign-On (SSO) that need to be configured as part of the migration and adoption towards GitLab or GitLab.com?

After having a technical scoping/sizing conversation with your customer, GitLab Partners find our GitLab Channel Service Packages helpful. These contain templated Data Sheets, Statements of Work (SOWs), and Project Plans. GitLab Partners are welcome to take and use these GitLab Channel Service Packages as templates for your customer work. Rebranding and rewording towards your unique technical service offering is encouraged. The table also outlines the GitLab expectations for the certifications held by our partners under the Aligned Partner Certification column.

The Migration Readiness Checklist, provided by GitLab Professional Services, provides a helpful example for you to use. It includes technical asks for Access, Communication, User migration planning, Migration Preparation, Wave Planning, Post Migration Checks, Post Migration Considerations, and Getting the most out of your investment. This document assumes the usage of Congregate, an open-source command line interface (CLI) migration tool from GitLab. Congregate is the preferred method used by GitLab Professional Services.

Communicating clearly What are a customer’s obligations and responsibilities prior to, during, and after a migration? and What level of instance access and permission are needed for migrating? with your customer will also ensure a smooth migration.

From other DevOps platforms to GitLab

To migrate projects from systems other than GitLab, please review the list of Supported import sources and Other Import Sources (anchor link on the same page).

Migrating pipelines from other systems, like Jenkins, is a value-added manual development process. We encourage our partners to scope by understanding the number of pipelines, current pipeline performance, environmental variables, and secrets used. Partners find a time and materials style contract helpful when consulting on developing pipelines between other source systems and GitLab’s pipeline syntax.

From GitLab self-managed to GitLab self-managed

The best way to migrate from one self-managed GitLab server to another is to perform a full backup at the source instance and then a restore at the target instance. Step-by-step directions are available on our Migrate to a new server docs page.

Air-gapped environments

GitLab can be installed and operated in offline environments. This setup makes migration projects more complex.

• Congregate, an open-source command line interface (CLI) migration tool from GitLab, does support Air-gapped environments. See Support air-gapped environment migrations and Migrating data in an air-gapped environment

• Direct transfer doesn’t support this. Project/export import is a workaround. See the GitLab issue titled Direct transfer - Support for air-gapped solutions and Maintain project and group file-based import/export as a workaround for migrations over air-gapped networks and to serve other use cases for nuanced technical details on performing this.

From GitLab self-managed to GitLab SaaS or the other way around

Choosing from the three different options for a customer migration depends on understanding your customer’s needs post-migration. A full technical page comparing in a table format the pros and cons of each method is outlined in Migration features. While Congregate supports most Features to be migrated, migrating to/from GitLab.com with Congregate requires the GitLab Professional Services team due to restricted access to the GitLab.com SaaS (multi-tenant) data. Your migration service may be achieved using one of the other methods.

There are three different options for these migrations.

1. File exports

For cases that direct transfer can’t or won’t cover. A good example would be air-gapped environments - see above.

• Migrating projects using file exports

• Items that are exported via file exports

• Items that are not exported via file exports

• Project import and export API

• Group import and export API

2. Direct transfer (Beta)

This feature was recently released and is the direction our product team is moving toward for migrating GitLab projects from instance to instance or SaaS. Please review the following resources:

• Migrated group items (direct transfer)

• Migrated project items (direct transfer)

3. Congregate

Congregate - used by GitLab Professional Services - is GitLab’s most mature migration solution and supports many options. Note that migrations to SaaS require the involvement of GitLab PS due to restricted access to GitLab SaaS (multi-tenant) data. More information about the latter can be found here.

Important to note about Congregate:

• Congregate Migration Features Matrix

• Migration Readiness Checklist

• Customer’s obligations and responsibilities - Congregate FAMQ

• Limitations of Self-Managed to SaaS migrations via Congregate - Congregate FAMQ

GitLab Professional Migration Services

The GitLab Professional Services team has a full-service catalog of offerings available for direct customers. Partners may review the offerings for inspiration towards delivering similar Professional (consultative) Service offerings.

The GitLab Professional Services Migration Package is one popular offering.