Migrate GitLab.com to self-managed GitLab

Move GitLab.com projects to self-managed GitLab with an export coverage matrix, user mapping, CI and registry rebuilds, reconciliation and rollback checks.

Last updated

In short

  • Direct transfer and file export have different coverage and version constraints.
  • CI secrets, registries and automation need explicit migration work.
  • Repository equality does not prove project-history or permission fidelity.
On this page (7)

Migration plans · Part of GitLab

Choose the migration method against the required objects

Moving GitLab.com work to a self-managed instance can preserve much more than Git commits, but no method should be assumed to transfer every surrounding service. Select the method after inventorying repositories, issues, merge requests, identities, CI, registries and integrations.

This is a reference migration procedure, not a completed rehearsal. GitLab recommends direct transfer for many scenarios and documents file exports for portable or offline movement. Record the destination version, edition and enabled import settings; coverage can vary by version and method.

Classify transfer, rebuild and archive work

Object Planned treatment Reconciliation
Git branches and tags Transfer through selected method Compare ref names and commit hashes
Issues, merge requests and comments Verify supported transfer coverage Counts plus sampled authors, timestamps and links
Users and memberships Create/map identities through supported process Effective roles and contribution attribution
CI variables and tokens Recreate securely Scope, protection and expiry reviewed
Runners and deployment access Register and configure separately Synthetic pipeline and denied-access tests
Container and package registries Separate copy or rebuild plan Required versions and digests available
LFS objects and uploads Verify method-specific inclusion Download and content checks
Webhooks, schedules and mirrors Recreate and transfer active ownership No duplicate external execution
Pages and domains Separate service configuration DNS, certificate and published content checks

Use the current migrated-items list for the chosen release. It explicitly distinguishes transferred and excluded objects. Treat credentials and external automation as deliberate rebuild work rather than trying to recover secrets from an export archive.

Prepare identities and access before importing

Choose the self-managed authentication method and stable user identifiers. If Keycloak is part of the target, validate GitLab SSO before the migration window. Map source users to destination users through the supported process and document unresolved or inactive contributors.

Do not assign all imported work to the migration administrator merely to simplify an import unless that loss of attribution is explicitly accepted. Contribution history, ownership and effective permission are different checks. A preserved author name does not prove the person has the right access after migration.

Create a target permission matrix for owner, maintainer, developer, reporter and external collaborator cases as applicable. Verify private-project visibility and protected-branch rules with synthetic accounts. Review inherited group membership, not just direct project membership.

Rehearse a representative group

Select a group containing a small repository, a larger repository, LFS content, an active merge request, uploads and a CI pipeline. Record source and destination versions and the exact import method. Keep the target private and prevent imported automation from reaching production during rehearsal.

Compare branch and tag hashes first. Then inspect issue and merge-request threads, attachments, labels, milestones and cross-project references. Rebuild CI variables from the approved secret source, using new target credentials where possible. Run a synthetic pipeline against test infrastructure and verify artifact and registry access.

File exports are not a full backup substitute; GitLab’s export documentation explicitly cautions against treating them that way. Keep the source accessible and maintain independent recovery arrangements for the new instance.

Rebuild the operational envelope

A self-managed GitLab service needs database and repository storage backups, configuration and secret recovery, monitoring, upgrades, mail delivery and capacity planning. Record which team owns each responsibility. Match the target licence to the required features rather than assuming a GitLab.com subscription transfers unchanged.

Separate CI runner infrastructure from Git hosting. The runner isolation guide describes the relevant trust boundary. Importing a pipeline definition should not automatically give unreviewed jobs access to the new host or production network.

Recreate webhooks and scheduled jobs in a disabled state until cutover. Rotate deploy tokens and service credentials deliberately. Keep an inventory of external systems that still reference GitLab.com URLs, including package consumers, build badges, issue links and developer remotes.

Cut over with a final change boundary

Announce a write freeze or another explicit change-control boundary for the affected group. Capture the last source refs and the final set of project changes. Complete the supported final transfer or reconciliation procedure, then validate before opening the target to writes.

Cutover gate Passing evidence
Repository state Required refs match expected hashes
Project data Agreed history sample and counts reconcile
Permissions Synthetic users have correct positive and negative access
CI and deployment Approved pipeline runs with scoped credentials
Registries and LFS Required objects download correctly
External integrations New endpoints work without duplicate triggers
Recovery Target backup and restore procedure is ready

Update developer remotes and external integrations through a controlled checklist. Keep the source read-only for the agreed transition period where possible, clearly indicating the new authoritative location.

Roll back without discarding new work

Before the target accepts writes, rollback can often mean returning users to the unchanged source. After new commits, issues or comments exist on the target, those changes need reconciliation. Preserve both histories and determine which objects can be transferred back or manually recorded.

Disable target automation before restoring source triggers. Rotate or revoke temporary migration credentials and retain sanitized migration evidence. Retire the source only after owners accept repository fidelity, project history, permissions and operational recovery. That is the boundary between a successful import and a completed migration.

Sources and further reading

Use the linked documentation to confirm the version, edition and contract that apply to your project.

Scope our GitLab move

Bring group sizes, required history, CI and registry dependencies, and the self-managed GitLab edition you intend to run.