GitLab 18 to 19 upgrade

The upgrade cannot jump straight from 18.x to 19.x. GitLab requires upgrades to pass through required upgrade stops, and since GitLab 17.5 those fall at x.2, x.5, x.8 and x.11. For an 18 to 19 move, the instance must reach 18.11 first, complete its background migrations there, and only then move to the first 19.x release. Confirm the exact path against the GitLab upgrade paths documentation before you schedule anything, because the documented path is the authority for your starting version. Plan each hop as a separate change with its own backup and rollback point.

PostgreSQL 17 must be in place before GitLab 19.0, whether the database is the bundled one or an external cluster you manage. Treat this as a prerequisite change, not something the GitLab upgrade will do for you. Check the current PostgreSQL version on the primary, and confirm with GitLab which PostgreSQL version the 19.0 release requires and whether the bundled database is handled differently in your installation method. Major PostgreSQL upgrades are also excluded from the zero-downtime procedure, because they change the on-disk format and typically need a dump-and-restore, pg_upgrade or logical replication approach with a planned write freeze. That means a separate maintenance window, a rehearsed rollback and a fresh backup taken just before the cutover, even on a multi-node deployment that otherwise upgrades without downtime.

Redis 7 is the other component to verify, and the check is for the target version, not only the one you run today. Confirm in the 19.x release notes and installation requirements which Redis major version the target release supports, and whether your Redis (bundled or external, including any Sentinel setup) meets it. Record the result alongside the PostgreSQL check so both prerequisites are signed off before the 18.11 stop begins. A prerequisite that is only discovered during the 19.0 step leaves you with a half-upgraded instance and a rollback that may not be clean.

The number of required stops is the first driver of duration. An instance that starts on an early 18.x release has to pass through each stop, such as 18.2, 18.5, 18.8 and 18.11, before 19.0, and each hop needs its own backup, post-upgrade checks and time for batched background migrations to reach Finished. Check the current version in the Admin area and map the full path against the GitLab upgrade paths documentation before setting a window. Database size is the second driver. A larger PostgreSQL data set lengthens the backup, the migrations and the restore point you would rely on if a hop fails, so ask for the database size and migration status as part of scoping.

Configuration and topology add the most variation. A heavily customized gitlab.rb file, with custom ports, storage paths, proxy settings or omnibus overrides, has to be reconciled with each release, and every change is a potential source of delay. External PostgreSQL or Redis instances move on their own schedule: PostgreSQL 17 and Redis 7 must be in place before the 19.0 hop, and an external database upgrade is a separate procedure with its own rollback plan. A multi-node topology behind a load balancer adds node ordering and health checks to every stop. The reference architectures recommend high availability for 3,000 or more users, so confirm whether the instance already runs that layout and who owns each component.

Runners and API consumers are often underestimated. A GitLab Runner fleet has to stay aligned with the server on major and minor versions, so a large fleet adds an upgrade cycle of its own. Integrations that call the REST or GraphQL API, along with scripts and deployment tools, need to be tested against 19.0 in staging, because removed or changed fields break silently. Most of this work is one-time: planning, staging rehearsal, integration test updates and the first production window. Recurring costs appear with each later stop, runner maintenance and any support retainer. When requesting a quote, ask for the number of stops, node and database topology, runner count, an inventory of API consumers, backup and rollback responsibilities, and the staging environment the work will use.

Run the full test plan on a restored copy of production before any change reaches the live instance, because the database migrations that run during the 18 to 19 path cannot be reversed by simply redeploying the old packages. Build the copy from a fresh backup taken with the gitlab-backup task, restore it onto identical operating system and PostgreSQL 17 infrastructure, and run the upgrade stops there in the same order you plan for production. Start the test with the API. Script regression calls against the endpoints your CI jobs, deployment tools, reporting scripts and chat bots actually use, authenticated with the same token types they use today. Compare status codes and response fields against the 18.x baseline, and record every field that disappears or changes type so you can check it against the GitLab 19 release notes before go-live. Confirm the list of changes with the GitLab documentation for your exact target version, since this guide does not list the removed items.

Next, test the container registry and runners as separate workloads. For the registry, push and pull images from a test project using the same credentials, storage backend and external URL your pipelines use, and confirm that tag listing, manifest pulls and cleanup policies behave as expected. For runners, register a test runner against the upgraded instance using the registration method your fleet will use, then run jobs on every executor type you operate, including Docker and autoscaling executors. Check that the runner version matches the GitLab major and minor version, as GitLab's Runner documentation advises, and that jobs that pull images, read CI variables and reach external services still succeed. Any runner that fails registration on the test copy should be fixed before the production window, not after.

Finish with authentication and recovery checks. Log in through each SSO and LDAP path your users rely on, including group sync and any SCIM provisioning, and confirm that existing sessions, personal access tokens and deploy tokens still work. Then perform a restore verification: restore the backup into an isolated environment, confirm that repositories, registry data, CI variables and the gitlab-secrets.json file are present, and time the restore so you know how long a real rollback would take. Once a migration has run on production, rollback means restoring the database and data from the backup taken before that stop, not reverting packages. That is why each backup taken before a required stop is the rollback anchor, and why you should confirm with your own team how long a restore takes before you accept the risk.