Howto: Migration from zengxs/gitlab to Official GitLab CE Image

[dopsun]

I’ve been running a GitLab instance on my Mac using the zengxs/gitlab Docker image. Following the recent notice recommending migration to the official GitLab CE image, I began the process. However, the notice didn’t clarify whether the zengxs image is fully compatible with the official one, nor did it provide guidance on selecting the correct version or performing the migration.

Steps I’ve Taken

1. Upgraded my local instance to zengxs/gitlab:18.2.1-ce-arm64
2. Backed up all local volumes
3. Switched to the official image: gitlab/gitlab-ce:18.2.1-ce.0
   (No changes made to the docker-compose.yml or any configuration files)
4. Verified that the instance runs correctly after migration

My instance so far works fine.

Request

May worth of provide some details in the notice:

• Which tag of zengxs image is compatible with which tag gitlab/gitlab-ce. And people like me can follow the path and moving forward.

Thank you for your great work!

[Giattuck]

i was using the image zengxs/gitlab:ee (without version number) in my compose file for the last two years. Periodically I updated my instance by just stopping the container, pulling and starting it again.

My last zengxs image was the 18.2.0.

I changed from zengxs/gitlab:ee to gitlab/gitlab-ee:latest on the compose, and updated as always, no more things to do.

[zengxs]

Hi, apologies for the late reply.

You are absolutely right, the zengxs/gitlab images are designed to be fully compatible with the official gitlab/gitlab-ce ones.

The migration path you took is perfect. Moving to the official image of the same version first is the safest way to confirm compatibility before you introduce any version-related changes.

For future upgrades from there, the key is to follow GitLab's official upgrade path. They don't support skipping major versions, so you often need to step through specific intermediate releases.

To make this super easy, GitLab actually provides an Upgrade Path tool that maps out the exact steps for you. You just need to input your current and target versions. You can find it here: https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/

So, the recommended strategy is exactly what you started: Backup, migrate to the same official version, and then use the tool to follow the official upgrade path.

You've made a great point, and we should have included this detail in the notice. Thanks for the valuable feedback!

And thank you for your great work.