GitLab 18 — when and how should I migrate?

Decide whether a self-managed GitLab estate can move to GitLab 18 without first remediating PostgreSQL dependencies now that PostgreSQL 14 and 15 support are removed and PostgreSQL 16 is the minimum.

Defer GitLab 18 unless PostgreSQL 16 remediation is already complete; only upgrade now if you control the DB cutover and can remove all 14/15 dependencies first.

Blockers

Who this is for

Candidates

Remediate PostgreSQL dependencies first, then upgrade to GitLab 18

As of 2026-04-08, GitLab 18.x requires PostgreSQL 16.5 or later, and GitLab documents that PostgreSQL 14 is not supported starting with GitLab 18. The GitLab Linux package matrix shows GitLab 18.0 ships with PostgreSQL 16.8 and aborts package upgrades if PostgreSQL has not already been upgraded to 16. Automatic PostgreSQL major upgrades only apply to single-node Linux package instances; Geo, HA, and external PostgreSQL deployments must be upgraded manually. For Helm-based installs, chart 9.0 removes support for PostgreSQL 14 and 15 and defaults the bundled subchart to PostgreSQL 16.

When to choose

Use this when the estate must move to GitLab 18 now or soon and you control the database upgrade path. This is the only path that aligns with GitLab 18 support policy once any node still depends on PostgreSQL 14 or 15.

Tradeoffs

Restores supportability and unblocks GitLab 18, but adds a separate PostgreSQL major-upgrade project with testing, extension checks, backup planning, and rollout sequencing.

Cautions

Do not assume GitLab will upgrade every topology for you. GitLab states PostgreSQL major upgrades are separate from zero-downtime upgrades, and external DB, Geo, and HA deployments require manual remediation. Helm users should also account for chart-level database changes and the documented need to handle the amcheck extension during 9.x upgrades.

Sources

Defer GitLab 18 and remain on a supported GitLab 17.x path until PostgreSQL 16 remediation is complete

As of 2026-04-08, GitLab 17.x supports PostgreSQL 14.14 and later, with a tested maximum through PostgreSQL 16.x, while GitLab 18.x raises the minimum to PostgreSQL 16.5. GitLab 17.10 and 17.11 already ship with PostgreSQL 16.8 in the Linux package matrix, and single-node package upgrades can automatically move to PostgreSQL 16 unless opted out. This makes GitLab 17.x the staging ground for estates that still have PostgreSQL 14 or 15 dependencies. The practical decision is to finish database remediation under 17.x, then take the GitLab 18 upgrade.

When to choose

Use this when there are external PostgreSQL, Geo, HA, extension-compatibility, or operational-change blockers that make an immediate PostgreSQL 16 cutover risky. It is the safer choice when supportability matters more than landing on GitLab 18 immediately.

Tradeoffs

Buys time for controlled remediation and testing, but delays access to GitLab 18 features and keeps the estate on an intermediate release track with additional upgrade-stop planning.

Cautions

This is a delay strategy, not a bypass. GitLab 18 still blocks unsupported PostgreSQL versions, so estates that postpone remediation must keep following GitLab 17 required upgrade stops and support windows while preparing the database move.

Sources

Facts updated: 2026-04-08
Published: 2026-04-08

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "GitLab 18 — when and how should I migrate?"
Missing something? Request coverage