This note is one of those “do not publish raw” work logs. It contains real domains, hostnames, addresses, and sensitive migration details.

That said, the migration pattern is good and worth turning into a draft.

1. Prepare the New Host Properly

The migration did not start with GitLab itself. It started with the supporting pieces:

  • mount the backup storage cleanly
  • prepare the mail behavior if the host will send notifications
  • install the SSL material that the stack expects

That may feel like side work, but GitLab migrations become harder when the surrounding host is only half prepared.

2. Install the Same GitLab Package Version Intentionally

The note installed a specific package version instead of whatever happened to be latest.

That is the right instinct for a restore-based migration:

  • pick the expected target version
  • install it explicitly
  • avoid introducing an accidental upgrade into the same change window

3. Preserve the SSH Identity

One practical detail I like in the note is the copy-over of the SSH host keys.

That matters because a GitLab move is not only about web traffic. It also touches:

  • existing Git remotes
  • runner trust
  • user SSH expectations

If the host identity changes unexpectedly, the migration feels broken even when the application restore is technically fine.

4. Move the Backups and Secrets Deliberately

The restore flow in the source note included:

  • /etc/gitlab
  • Redis state where applicable
  • the GitLab backup tarball
  • GitLab secrets

That is the right mental model. A GitLab restore is not just “copy one tar file and hope.”

5. Stop the Right Services Before Restore

The note explicitly stopped puma and sidekiq before the restore:

1
2
3

gitlab-ctl stop puma
gitlab-ctl stop sidekiq
gitlab-backup restore BACKUP=<backup-id>

This is one of those details you do not want to have to remember from memory in the middle of a migration window.

6. Validate the Result

The last part of the note was the most important:

  • run gitlab:check
  • run the secrets checks
  • validate artifacts, LFS, and uploads
  • test Git over SSH
  • test the registry and runners if those services are part of the same instance

That is how you turn “restore completed” into “migration is actually credible.”

Closing Thought

This draft still needs another cleanup pass before it is publishable, but the structure is already useful.

A GitLab migration is not one command. It is a chain of identity, storage, secrets, and validation steps that need to line up.