One of the easiest ways to make a GitLab upgrade harder than it needs to be is to treat it like a normal package bump. It usually is not.

This note came from a real GitLab upgrade where the installed version was 16.10.6-ee.0 and the target version was 17.0.1-ee.0. The important detail was that the path needed an intermediate stop at 16.11.3-ee.0.

That is the kind of thing I write down because it is easy to forget when you come back to the box months later.

The Situation

The server had GitLab Enterprise Edition installed at:

1

16.10.6-ee.0

And the available package candidate had already moved ahead to:

1

17.0.1-ee.0

I confirmed that with:

1

apt-cache policy gitlab-ee

The version table showed both the current package and the available intermediary 16.11.x releases.

The Important Part: Follow the Upgrade Path

This was not a case where I wanted to jump straight from 16.10.6 to 17.0.1.

The correct move was to follow GitLab’s documented upgrade path and install the required intermediate release first:

1
2

apt-get install gitlab-ee=16.11.3-ee.0
apt-get install gitlab-ee=17.0.1-ee.0

That is the whole reason this note is worth keeping. On systems like GitLab, version sequencing is part of the upgrade, not optional ceremony.

Step 1: Upgrade to 16.11.3

The first upgrade completed successfully and reconfigured the instance cleanly.

One thing that stood out in the output was a warning about the Cinc client release being end-of-life, which was useful to notice, even though it was not the immediate blocker for the GitLab upgrade itself.

After the 16.11.3-ee.0 step, the service stack came back with the usual components healthy:

  • gitaly
  • gitlab-workhorse
  • nginx
  • postgresql
  • puma
  • redis
  • registry
  • sidekiq

The operational lesson here is simple: after the intermediate version completes, do not rush. Read the output, confirm services came back, and only then continue.

Step 2: Upgrade to 17.0.1

Once the instance was stable on 16.11.3-ee.0, I moved to the actual target version:

1

apt-get install gitlab-ee=17.0.1-ee.0

That step also completed successfully and restarted the GitLab service set cleanly.

Again, the output was the important signal. I wanted to see the platform reconfigure successfully and return each core service to a healthy running state before treating the upgrade as done.

What I Checked After Each Step

For me, a package manager saying “done” is only the start of validation.

After each upgrade hop, I wanted to confirm:

  • GitLab reconfiguration completed without a hard failure
  • the expected services restarted
  • PostgreSQL and Redis were still healthy
  • Puma, Sidekiq, and Workhorse came back cleanly
  • the registry was still running if in use

If GitLab had misbehaved after either hop, the next step would have been:

1

sudo gitlab-ctl restart

That recommendation was echoed in the installer output itself.

Why I Like Notes Like This

This is not a glamorous post, but it is useful because it captures the real operational question:

Can I safely move from one GitLab major version to another, and what exact stepping stone did I use?

That is the kind of detail that disappears fastest when you do not write it down.

Closing Thought

GitLab upgrades are usually less about typing commands and more about respecting the path. The key lesson from this one was not the package names. It was remembering that 16.10.6 to 17.0.1 was a two-step move, not a one-step move.