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.

If you prefer consuming content in an audiovisual format, and you are a GitLab Partner at the same time, you can watch the following videos in what a bunch of GitLab Ecosystem Solutions Architects discuss the content of this Handbook page and more: For the links in this section, login to our GitLab Partner Portal first, then click the links:

1. GitLab Partner Migration Services Knowledge Transfer 1/2
2. GitLab Partner Migration Services Knowledge Transfer 2/2

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? Consider running GitLab Evaluate, an open source a script that can be run to gather information about all projects of a GitLab Instance and/or Group (including subgroups). Also consider running Project storage report to create a CSV report for project storage usage. Reports for a single group as well as all projects on a self-managed instance are supported.
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? Would a GitLab Partner Led Optimization Service be a better first step?
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 template 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.

Similarly, the Migration group of our GitLab Professional Services Delivery Kits can be very helpful, because these projects “provide step-by-step instructions on delivering everything from a single activity to an entire statement of work (SOW)”

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. There are automated tools for such migrations out there, but there’s none officially supported by GitLab. 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.

Please note that this migration method only works if the source and target instances have the exact same version. If it’s not the case for your customer’s environments (typically it’s the source system which lags behind), then our Upgrade Path tool can help with planning the necessary upgrades on the source system. (Make sure to do a full backup BEFORE the upgrades!)

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)

GitLab Log Analysis Tool

This tool could come in handy when one needs to debug a filed Direct Transfer migration.

It spins up a complete ELK Stack (Elasticsearch, Logstash, Kibana) environment specifically tailored for GitLab logs.

Clone the repo and then with just a single command, the environment is ready to go! Customer’s logs will automatically get indexed, and Kibana will launch with pre-configured dashboards, giving you an immediate visual analysis of GitLabSOS, KubeSOS, or GDK logs.

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

Migrating package/container registries

Recommendation (regardless of the use of Congregate): “We typically suggest customers establish pipeline jobs in GitLab after source code migration to publish these containers/packages to the GitLab registry as desired. For customers who are interested in maintaining audit history, we suggest keeping the legacy package/container registry tool around with a reduced license spend until the audit window expires.”

In case the migration of history is also required, the packages importer tool can be used. Documentation here.

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.