Why is a GitLab migration more than copying files?
Self-managed GitLab combines repositories with its database, configuration, secrets, artifacts, LFS, packages, Container Registry and CI/CD components.
A plan limited to visible repositories can leave pipelines, Registry, webhooks or Runner workflows incomplete even when users can sign in.
- Git repositories and wikis
- PostgreSQL database
- LFS, artifacts, uploads and packages
- Container Registry
- Runner registrations and execution capacity
- Secrets, SSH keys, TLS and external integrations
Current-state information that can be collected safely
The first step is to record the source version and health rather than change the environment. These read-only checks support inventory collection.
Outputs can contain internal addresses or access details and should be sanitized before sharing.
sudo gitlab-rake gitlab:env:info
sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-ctl status
df -h- GitLab version and installation type
- Operating system and target capacity
- Failed or disabled GitLab components
- Data size and growth headroom
- Problems that already exist on the source
Why must the upgrade path be established first?
Source and target GitLab versions cannot be selected arbitrarily. Some upgrades require mandatory intermediate versions and completed background migrations.
The exact path must be checked against current GitLab documentation at delivery time after confirming Edition, packaging and target platform.
- Are source and target on the same Edition?
- Are mandatory upgrade stops required?
- Have background migrations completed?
- Is the target OS and architecture supported?
- Are PostgreSQL and Registry dependencies compatible?
Downtime, DNS and final synchronization
The plan must define how writes to repositories, issues, pipelines and Registry data are controlled during cutover.
The maintenance window needs separate time for final synchronization, traffic switching, user validation and rollback if acceptance fails.
- Read-only or maintenance period communicated to users
- DNS TTL and reverse-proxy behavior
- Control of the final data change
- Preventing Runners from executing against the wrong environment
- Conditions for reopening the source after a failed cutover
A login page is not sufficient validation
Successful login does not prove the migration is complete. Representative projects need clone/push, pipeline, artifact, LFS, Registry and webhook validation.
Acceptance criteria, test owners and expected outcomes should be documented before execution.
- User, group and project permissions
- SSH and HTTPS clone/push
- Runner and pipeline execution
- LFS, artifact and package download
- Container Registry push/pull
- Webhooks, email, LDAP/SAML and integrations
- Backup and monitoring jobs
Where does environment-specific delivery begin?
Backup creation, restore, secret transfer, upgrades, Registry migration and cutover can cause data loss or extended downtime. A generic command recipe is therefore unsafe for production.
Atlas Infrastructure prepares the inventory, supported version path, rehearsal, written cutover/rollback plan and post-migration validation for the specific environment.
- Business-critical GitLab environment
- Large Registry, LFS or artifact volume
- Multiple Runners and deployment targets
- LDAP/SAML, object storage or external PostgreSQL
- Short maintenance window or mandatory rollback
Common questions about GitLab
Can GitLab be migrated with zero downtime?
Downtime can be reduced for some architectures, but zero downtime is not a responsible promise for every environment. The write pattern, data size and version path determine the realistic window.
Is copying GitLab directories with rsync sufficient?
Usually not. Database consistency, secrets, Registry data and version compatibility must be addressed together.
Will Runners work automatically after migration?
Runner URLs, tokens, certificates, network access, executors and secret dependencies must be validated independently.