Migrate from the Linux package to the Helm chart

This guide will help you migrate from a package-based GitLab installation to the Helm chart.


Before the migration, a few prerequisites must be met:

  • The package-based GitLab instance must be up and running. Run gitlab-ctl status and confirm no services report a down state.
  • It is a good practice to verify the integrity of Git repositories prior to the migration.
  • A Helm charts based deployment running the same GitLab version as the package-based installation is required.
  • You need to set up the object storage which the Helm chart based deployment will 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

JUnit test report artifact (junit.xml.gz) migration was not supported until GitLab 12.8 by the gitlab:artifacts:migrate script below.
  1. Migrate any existing files (uploads, artifacts, LFS objects) from the package-based installation to object storage:

    1. Modify /etc/gitlab/gitlab.rb file and configure object storage for:

      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 Packages to object storage:

      gitlab-rake gitlab:packages:migrate
    6. Migrate existing uploads to object storage:

      sudo gitlab-rake gitlab:uploads:migrate:all

      See documentation.

    7. Visit the 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.
  2. Create a backup tarball and exclude the already migrated uploads:

    sudo gitlab-rake gitlab:backup:create SKIP=artifacts,lfs,uploads

    The backup file will be stored under /var/opt/gitlab/backups, unless you explicitly changed it.

  3. Restore from the package-based installation to the Helm chart, starting with the secrets. You will need to migrate the values of /etc/gitlab/gitlab-secrets.json to the YAML file that will be used by Helm.
  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 the package-based installation are restored. Also, verify if the uploaded files (avatars, files uploaded to issues, etc.) are loaded fine.