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.
