• Prerequisites
• Migration Steps

Migrating from Omnibus-GitLab package based installation

Prerequisites

• Deployment using Omnibus GitLab package needs to be running. Run gitlab-ctl status and confirm no services report a down state.

• It is good practice to verify the integrity of Git repositories prior to migration. See the integrity check Rake task documentation for how to perform this task.

• /etc/gitlab/gitlab-secrets.json file from package based installation.

• A Helm charts based deployment running the same GitLab version as the Omnibus GitLab package-based installation.

• Object storage service which the Helm chart based deployment is configured to use. For production use, we recommend you use an external object storage and have the login credentials to access it ready. If you are using the built-in MinIO service, read the docs on how to grab the login credentials from it.

Migration Steps

1. Migrate existing files (uploads, artifacts, lfs objects) from package based installation to object storage.

   1. Modify /etc/gitlab/gitlab.rb file and configure object storage for uploads, artifacts and LFS.

      Note: This must be the same object storage service that the Helm charts based deployment is connected to.

   2. Run reconfigure to apply the changes

      sudo gitlab-ctl reconfigure
      

   3. Migrate existing artifacts to object storage

      sudo gitlab-rake gitlab:artifacts:migrate
      

   4. Migrate existing LFS objects to object storage

      sudo gitlab-rake gitlab:lfs:migrate
      

   5. Migrate existing uploads to object storage

      sudo gitlab-rake gitlab:uploads:migrate:all
      

      See documentation.

   6. Visit the Omnibus GitLab package-based GitLab instance and make sure the uploads are available. For example check if user, group and project avatars are rendered fine, image and other files added to issues load correctly, etc.

   7. Move the uploaded files from their current location so that they won’t end up in the tarball. The default locations are:

      • uploads: /var/opt/gitlab/gitlab-rails/uploads/
      • lfs: /var/opt/gitlab/gitlab-rails/shared/lfs-objects
      • artifacts: /var/opt/gitlab/gitlab-rails/shared/artifacts

      sudo mv /var/opt/gitlab/gitlab-rails/uploads{,.bak}
      sudo mv /var/opt/gitlab/gitlab-rails/shared/lfs-objects{,.bak}
      sudo mv /var/opt/gitlab/gitlab-rails/shared/artifacts{,.bak}
      

   8. Run reconfigure to recreate empty directories in place, so backup task won’t fail.

      sudo gitlab-ctl reconfigure
      

2. Create backup tarball

   sudo gitlab-rake gitlab:backup:create
   

   The backup file will be stored in /var/opt/gitlab/backups directory, unless explicitly changed in gitlab.rb.

3. Follow official documentation on how to restore from package based installation to the Helm chart, starting with the secrets.

4. Restart all pods to make sure changes are applied

   kubectl delete pods -lrelease=<helm release name>
   

5. Visit the Helm based deployment and confirm projects, groups, users, issues etc. that existed in Omnibus GitLab package-based installation are restored. Also verify if the uploaded files (avatars, files uploaded to issues, etc.) are loaded fine.