When migrating GitLab instances, you need to preserve:

• Git repositories with full history
• Merge requests and comments
• Issue tracking data
• Wiki content
• CI/CD pipeline configurations
• User accounts and permissions

Use the official GitLab backup command:

sudo gitlab-backup create STRATEGY=copy

This creates a tar archive in /var/opt/gitlab/backups containing:

• SQL database dump (postgresql)
• Redis database
• Repository bundles (.bundle files)
• Uploads and attachments

Edit /etc/gitlab/gitlab.rb to ensure proper backup settings:

gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"
gitlab_rails['backup_archive_permissions'] = 0644
gitlab_rails['backup_keep_time'] = 604800

Then reconfigure GitLab:

sudo gitlab-ctl reconfigure

Prerequisites:

1. Same GitLab version on both servers
2. Identical configuration (especially secrets)
3. Sufficient disk space

Restoration command:

sudo gitlab-backup restore BACKUP=timestamp_of_backup

Check these critical components:

sudo gitlab-rake gitlab:check SANITIZE=true
sudo gitlab-rake cache:clear

Verify repository integrity:

sudo find /var/opt/gitlab/git-data/repositories -name '*.git' -type d | while read repo; do
  sudo -u git -H git -C "$repo" fsck
done

For repositories >10GB, consider these optimizations:

gitlab_rails['backup_upload_connection'] = {
  'provider' => 'AWS',
  'region' => 'us-east-1',
  'aws_access_key_id' => 'AKIAxxx',
  'aws_secret_access_key' => 'secret'
}
gitlab_rails['backup_upload_remote_directory'] = 'gitlab-backups'

Create a cron job for daily backups:

0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1

Add email notifications:

gitlab_rails['backup_pg_schema'] = 'public'
gitlab_rails['backup_upload_connection'] = {
  'encryption' => 'AES256',
  'server_side_encryption' => 'AES256'
}

If restoration fails, check:

• /var/log/gitlab/gitlab-rails/production.log
• /var/log/gitlab/gitlab-workhorse/current
• journalctl -u gitlab

Common fixes:

sudo gitlab-ctl restart
sudo gitlab-rake cache:clear
sudo gitlab-rake assets:clean assets:precompile

---

Before executing a migration, it's crucial to understand what GitLab's backup package includes:

• Git repositories with full commit history
• Database (issues, merge requests, users, etc.)
• Attachments (LFS objects, CI artifacts)
• Configuration files (secrets, SSL certificates)
• Build traces and container registry (if configured)

The official gitlab-rake command handles most backup scenarios:

# As root or gitlab user
sudo gitlab-backup create STRATEGY=copy

For large installations, consider these parameters:

# Skip container registry to reduce size
sudo gitlab-backup create SKIP=registry

# Backup specific repositories only
sudo gitlab-backup create REPOSITORIES_PATTERN='project1|project2'

Always verify your backup integrity before migration:

# List backup contents
tar -ztvf /var/opt/gitlab/backups/1657812345_2022_07_14_gitlab_backup.tar

# Check database consistency
sudo gitlab-rake gitlab:check

On the new server with identical GitLab version:

# Stop critical services
sudo gitlab-ctl stop unicorn
sudo gitlab-ctl stop sidekiq

# Restore (replace TIMESTAMP)
sudo gitlab-backup restore BACKUP=1657812345_2022_07_14

# Reconfigure and restart
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

For complex environments:

# When restoring to different server name
sudo gitlab-rake gitlab:backup:restore force=yes

# For Docker-based installations
docker exec -it gitlab gitlab-rake gitlab:backup:restore

• Verify repository access via git ls-remote
• Check CI/CD pipeline status
• Test webhooks and integrations
• Validate user permissions

Remember to test the restoration process in a staging environment before production migration. The entire process may take several hours for large GitLab instances.