Working out the GitLab upgrade path from your current version
If your self-managed GitLab instance is several versions behind, the upgrade must pass through required upgrade stops at x.2, x.5, x.8 and x.11. Since GitLab 17.5, each of these stops is a planning point, not a suggestion: you land on the stop, confirm the instance is healthy and then continue. Skipping a stop is not a shortcut you can take later, so the path has to be fixed before any change window is booked. The examples in the GitLab upgrade paths documentation show how the stops fall in practice: 18.2, 18.5, 18.8 and 18.11 on the 18.x line, and 19.2, 19.5, 19.8 and 19.11 on the 19.x line. Work backward from your target version to the nearest stop at or below it, then forward from your current version to the next stop, and write the sequence down. An instance on 17.x, for example, reaches 18.2 first. Confirm each hop against the upgrade paths page at the time you run it, because the stop list is the authoritative reference and this page can lag behind it. The reason falling behind is risky is the maintenance policy. According to the GitLab maintenance policy, bug fixes are backported only to the current stable release, while security fixes also reach the previous two monthly releases. The maintained range at the time of writing is 19.5, 19.4 and 19.3, which means an instance on an older line gets security coverage only if it has kept pace. Ask the platform owner which version is running today, how many stops lie between it and the target, and whether the change calendar can absorb one planned hop per stop.
What changes at each stop and what you must test
This table compares what each release type asks of your upgrade plan, from required stops to patch releases and Runner alignment. Read it as a checklist: the cadence rows set how often you revisit the plan, and the stop row sets which versions you cannot skip. Confirm stop-specific removals and prerequisites in the official upgrade notes for your target version before you schedule any hop.
| Change | What it means for your upgrade | Action you need to take |
|---|---|---|
| Required stop at x.2, x.5, x.8 and x.11 | Since GitLab 17.5, upgrades must pass through these versions, for example 18.2, 18.5, 18.8, 18.11, 19.2, 19.5, 19.8 and 19.11. | Map every hop from your current version to the target, and stop at each required version in order. |
| Removed components and prerequisites at each stop | Each stop can remove features or raise minimum database, Redis or operating system versions. | Read the upgrade notes for every stop you pass through and confirm prerequisites before you start that hop. |
| Background migrations between stops | Batched background migrations can still be running after an upgrade and must finish before the next hop. | Confirm each migration shows Finished before moving to the next required stop. |
| Yearly major release (GitLab 20.0 planned for May 2027) | A major release can carry breaking changes beyond the required stops, and it arrives once a year. | Schedule a review of the major release notes and the deprecations list each year, well before you plan the jump. |
| Monthly minor releases (third Thursday of each month) | Minor releases add features and changes, and the stop versions fall within this sequence. | Track the release cadence so your plan names the next target minor release and its stop status. |
| Twice-monthly patch releases | Patch releases carry fixes, and security fixes are backported to the previous two monthly releases as well as the current one. | Apply security patches to your current line promptly, and test patch releases in a staging copy before production. |
| Bug fix versus security backport policy | Bug fixes reach only the current stable release, while security fixes reach the previous two monthly releases too. | If you run an older monthly release, expect security fixes but not bug fixes, and factor that into your target choice. |
| Runner major.minor alignment | GitLab Runner should match GitLab's major and minor versions, so each GitLab hop can require a Runner hop. | Plan Runner upgrades alongside each GitLab stop and confirm the alignment rule in the Runner documentation. |
Why background migrations decide how long each hop takes
Background migrations, not the package install, usually set the length of each hop in a GitLab upgrade path. Between required stops, GitLab may run batched background migrations that rewrite or backfill data in the database. Each one must show as finished before you move to the next stop, so a hop cannot be planned as a fixed block of time. The work scales with the amount of data your instance holds and with any backlog of migrations left from earlier hops, so two instances on the same versions can need very different windows.
Before each hop, check migration status in the Admin area and confirm that no batched background migration is still pending or failed. The same information is available from the database, which is the better route for large instances or scripted checks. Record the number of pending jobs and the time each one has taken so far, then use the trend from a staging copy of your own data to size the window. Ask your team to confirm the current migration behavior for each target version in the upgrade documentation, since requirements change between stops. Read the GitLab upgrade paths documentation for the stop list that applies to your version.
Plan for migrations that stall or fail. Decide in advance who may retry or finalize a failed migration, how long the instance can stay in a maintenance state, and what rollback looks like if the database is not yet ready for the next release. Take a verified backup immediately before each hop so a failed migration does not turn into a data recovery exercise. If your staging run shows migrations that take longer than your approved window, schedule the hop earlier in the change calendar rather than compressing the migration step in production.
What to prepare before the first hop
Each hop changes the instance in ways that are hard to reverse, so the preparation work comes first. The six items below cover the restore point, the baseline you are upgrading from, the dependent systems that must move with GitLab, and the test environment and window in which the hops are rehearsed.
Prove the backup restores
A backup file that has never been restored is an assumption, not a restore point. Run a full backup, then restore it to a separate host and confirm that projects, repositories, CI/CD configuration and uploads are present. Check the configuration and secrets files separately, because the database and repository backup does not capture everything an instance needs to run. Record how long the restore took, since that figure bounds your rollback time. Follow the backup and restore documentation for your installation method.
Inventory the installation method
The upgrade procedure depends on how GitLab was installed. Linux package, Helm chart, GitLab Operator, Docker and source installs each follow different upgrade steps, and mixing them up during a hop is a common cause of failed runs. Record the installed version, the method, the database and Redis locations (bundled or external), and any custom configuration in gitlab.rb or values files. Ask whether the instance is a single node or part of a multi-node layout, because that changes the procedure entirely.
List integrations that depend on versions
Every system that talks to GitLab through its API or webhooks may need an update or a test after a hop. Typical examples are issue trackers, secrets managers, Kubernetes clusters, chat tools and external CI systems. Write down each integration, its owner, the credential it uses and whether it has been tested against the target release. Remove integrations that no longer have an owner, because each one adds a test case to every hop.
Match runner versions to GitLab
GitLab Runner executes CI/CD jobs and should stay aligned with the server on major and minor versions. Inventory every runner fleet, its version, its executor type and the tags it serves. Plan to upgrade runners in step with the server, not as an afterthought, because a mismatched fleet can fail jobs that worked before the hop. Confirm which runner fleets are used by production pipelines, since those need the most careful sequencing.
Build a staging instance from backup
Restore a recent backup to a staging instance that matches production in edition, installation method, database version and approximate size. Run every required stop there first and time each hop. Staging is where background migrations reveal slow tables and failed steps, so treat its timings as the basis for the production window. A staging instance that differs in configuration or data volume will give timings that cannot be trusted.
Confirm OS, PostgreSQL and Redis floors
Each target release sets minimum versions for the operating system, PostgreSQL and Redis, and some hops require those components to be upgraded first. Compare the current versions with the requirements listed for every required stop on the path, not only the final release. Schedule any OS or database upgrade as its own change with its own rollback point. Confirm with the upgrade paths and release documentation before you commit a window.
The upgrade sequence, stop by stop
The sequence turns a distant version into a series of supported hops, each ending at a required stop with a verified instance and a known rollback point. It is the path logic behind the upgrade, and the multi-node procedure for each hop is covered on the zero-downtime page.
Confirm current version and target stop
Record the installed GitLab version, the edition, and the install method, then map the path to the target using the upgrade paths documentation. Since GitLab 17.5 the required stops fall at x.2, x.5, x.8 and x.11, so the first hop ends at the next stop above your version and the target is reached through each stop in turn. Confirm the exact list with the upgrade paths page for your starting version, because the path depends on where you begin. The output is a written hop list that names every stop and the patch release you will install at each one.
Take and test a backup
Create a full GitLab backup and store it outside the instance, including the configuration and secrets files that the backup task does not capture. Then restore it to a separate test host at the current version and confirm that projects, pipelines and users load. This restored copy is your rollback point for the first hop, and it should be tested before any change is made to production. Done means a restore completed on the test host and the backup, configuration and secrets are recorded together in a known location.
Check background migrations are finished
Before leaving the current version, confirm that every batched background migration shows Finished in the Admin area or the database. A migration still running or failed when you start the next hop can block the upgrade or leave data in a partial state. Retry or finalize failed migrations as the background migrations guidance describes, and repeat the check before each subsequent stop. The check is complete when no migration is pending or failed for the version you are leaving.
Upgrade to the first required stop
Install the patch release of the first required stop, applying the platform prerequisites that the upgrade paths page lists for that version, such as PostgreSQL or Redis minimums and operating system support. Run the upgrade on a staging copy of the instance before production, and keep the backup from the earlier step available. The output is an instance running the stop version with the reconfigure and database migration steps completed without errors. If the hop fails, the rollback point is the backup restored to the prior version.
Verify health at the stop
Check the instance before moving on: run the health check and GitLab check tasks, confirm that background migrations have completed, review logs for repeated errors, and test a clone, a pipeline run and a sign-in. Verification also covers the integrations you rely on, such as the registry, runners and any external database. Your team should agree the exact pass criteria in advance. The step is closed when every check passes and the results are recorded, because a failed check here is the last point at which rolling back to the prior stop is simple.
Run the next hop and repeat to the target
Repeat the backup, migration check, upgrade and verification steps for each required stop until the target version is reached. Each stop becomes the new starting point, so the rollback point moves forward with it: a fresh backup taken at the last verified stop. Do not skip a stop, even when a later release looks reachable directly, because the path is set by the upgrade paths documentation. The output is a log of every hop with its version, backup identifier and verification result.
Upgrade Runners to the aligned version
After the server reaches the target, upgrade GitLab Runner so that its major and minor versions match the server, as the Runner documentation advises. Upgrade each runner fleet in a test environment first, then in production, and confirm that jobs execute and report status back to the instance. The rollback point for this step is the previous Runner binary or image, which you should keep until the first pipeline runs succeed. The step is complete when every runner reports the aligned version and a representative set of pipelines passes.
What makes a GitLab upgrade take longer
How many required upgrade stops does an old GitLab instance pass through?
The number of required stops is the main driver of total effort, because each stop is a separate upgrade with its own checks, backup and background migration wait. Since GitLab 17.5, required stops fall at x.2, x.5, x.8 and x.11, so an instance several minor versions behind may cross several of them. Each additional hop adds a planning step, a backup, a test cycle and a rollback point. Ask a partner to list every stop on your path, the target version for each hop, and whether they will test each hop on a copy of your data or only the final target. The GitLab upgrade paths documentation is the reference to check against your current version.
Does the size of the database and repositories change upgrade time?
Yes. Larger PostgreSQL databases and Git repository storage increase backup time, restore rehearsal time and the duration of post-upgrade migrations that rewrite data. Large repositories also slow the backup and copy steps that run before each hop. Ask for the database size, repository storage size, number of projects and whether Gitaly storage is local or on shared storage, then ask the partner to time a backup and restore on a copy of production before quoting the window.
Why does a backlog of background migrations slow an upgrade?
Background migrations are batched data changes that GitLab runs after an upgrade, and the next upgrade cannot safely start until they finish. An instance that has skipped stops often has a larger backlog, so waiting time can exceed the time spent on the upgrade itself. Check the status of batched background migrations before planning, and ask the partner how they will handle failed or stalled migrations and whether they will schedule enough time between hops for them to complete.
How does custom gitlab.rb configuration affect an upgrade?
Heavy customization in gitlab.rb increases review time because settings can be deprecated, renamed or removed between versions, and each change must be checked against the target release. Environment-specific overrides, custom Nginx or Puma settings and hand-edited files on each node add more work when several nodes are involved. Ask the partner to diff your configuration against the target version, list each override with its owner and purpose, and confirm how configuration is kept under version control so it can be rolled back.
Do external PostgreSQL or Redis services add upgrade steps?
They do. When PostgreSQL or Redis is external to the bundled Linux package, the database or cache has its own upgrade track, backup routine and compatibility check that must be sequenced with GitLab. Major PostgreSQL upgrades are handled separately from the GitLab procedure, and the prerequisites for each target release must be met first. Ask for the current PostgreSQL and Redis versions, the owner of each service, the backup method, and whether a managed service is used, since managed services change who runs the database upgrade.
How do Geo and multi-node topologies change the upgrade work?
Each additional node, and each Geo secondary site, adds upgrade steps, ordering rules and verification. A multi-node instance usually requires a load balancer plan and a component-by-component sequence to avoid downtime, while Geo requires a clear upgrade order between primary and secondary sites and care with replication state and secrets. Ask the partner to document the node roles, the order of upgrades, how replication is paused and resumed, and what the downtime window is for each stop, if any.
Does the installation method change how long the upgrade takes?
It does. The Linux package, the Helm chart, the GitLab Operator, Docker and source installs each have different upgrade procedures, tooling and rollback methods. A Helm-based deployment, for example, requires chart-to-version mapping and runner order decisions that a Linux package install does not. Confirm which method runs in production, whether it has been modified from the default, and whether the team has tested that method before, since an unfamiliar method adds planning time.
How do integrations and the Runner fleet size affect upgrade effort?
More integrations and more Runners increase the number of components to test and the number of jobs that can fail during the window. Each integration with an issue tracker, secrets manager, Kubernetes cluster or chat system may depend on a specific API behavior, and Runners must stay aligned with the GitLab major and minor version. Ask for an inventory of integrations and Runner executors, the Runner versions in use, and the order in which Runners will be upgraded, then ask the partner to include a smoke test for each integration in the quote.
Testing and rolling back each hop
A single-node instance installed with the Linux package bundles PostgreSQL, Redis and Sidekiq on the same host, so one clean copy of the environment is the most practical test target. Build a staging server from the same package version, restore a recent production backup into it, and run each hop there before touching production. The rollback point is a full backup taken immediately before the upgrade, because reverting packages alone does not undo database migrations that have already run. Confirm with your own runbook how the GitLab backup task and the configuration files, including the secrets file, are captured, since restoring the database without matching secrets causes its own failures.
- Staging parity: Match the operating system, PostgreSQL and Redis versions and the installed package to production before the first hop.
- Pre-hop backup: Take a backup and copy
/etc/gitlabseparately, then confirm the archive is readable. - Restore test: Restore into staging at least once so the rollback path is known to work, not assumed.
- Post-hop checks: Run
gitlab-ctl status,gitlab-rake gitlab:checkandgitlab-rake gitlab:env:info, then confirm background migrations show as finished before the next hop. - Smoke tests: Sign in, push and clone a repository, run a pipeline on a Runner and open a merge request.
Record the output of each check so the next hop starts from a known state.
A Helm chart or GitLab Operator deployment separates the stateless GitLab components, which run on Kubernetes, from any stateful services you run elsewhere. The test environment should be a non-production namespace or cluster that mirrors your values files, ingress, storage classes and external database or object storage settings. Rollback is less a matter of reverting containers than of restoring data: the Kubernetes release history can return workloads to a previous chart version, but it cannot reverse database migrations or repository changes made after the hop. Keep a backup of the stateful services and the values files under version control so that a failed hop has a documented return path.
- Values under version control: Store the chart values and the chart version used for each hop so the exact release can be reproduced in staging.
- Stateful backups: Confirm the state of the external PostgreSQL, Redis and object storage backups before the hop, since Kubernetes rollback does not restore them.
- Runner order: Align Runner versions with the GitLab version, and check the Runner upgrade guidance before changing the server.
- Helm release history: Note the current revision so you know what a rollback command would return to, and test that command in staging.
- Post-hop checks: Check pod readiness for every component, run the toolbox health checks, and confirm migration jobs completed without errors.
If a hop fails partway, keep the environment in its current state and restore from backup instead of forcing further upgrades.
A multi-node instance, and any Geo deployment with a primary and secondary site, has more moving parts, so the test environment must include the load balancer, every application node and the replicated data. A Geo secondary is a warm standby kept continuously synchronized, which means a mistake on the primary is copied to the secondary unless replication is paused first. Rollback therefore starts with a clean backup and a documented replication checkpoint, not with a reverse-order package downgrade. Plan the test so that each component is upgraded in the sequence your zero-downtime procedure requires, and confirm with the GitLab documentation which steps apply to your architecture.
- Representative staging: Build a staging topology with the same node count, Gitaly storage layout and load balancer rules, even if it runs at smaller scale.
- Replication checkpoint: Pause replication at a known point before the hop so the secondary keeps a clean recovery state.
- Matching secrets: Verify that the secrets files match across sites and nodes before and after each hop.
- Node-by-node checks: After each node is upgraded, confirm it serves traffic through the load balancer and that background jobs are processing.
- Geo verification: Check replication status and sync lag on the secondary, and run a test restore or failover drill in staging before relying on it.
Do not resume replication on production until the post-hop checks show every node and site healthy.
Questions buyers ask about the GitLab upgrade path
What does a GitLab upgrade cost and what drives the price?
The cost is mostly the labor to plan, rehearse and run each hop, plus any infrastructure you add for a rehearsal environment. Your own staff are paid for their time, a partner is paid against the written scope, and both carry the work of checking backups, prerequisites and post-upgrade tests. Most of the one-time cost sits in the first upgrade. Recurring cost appears only if you keep a retainer for later releases. When you ask for a quote, request the list of hops, the environments covered, the prerequisites included (database, Redis, operating system, Runner versions), the rollback plan and what is excluded, such as a PostgreSQL major upgrade or Geo sites.
How long does each upgrade hop take?
Duration depends on the data and migrations in the instance, not on the version number alone. The main drivers are the size of the database, the number of repositories and CI artifacts, how many batched background migrations must finish before the next stop, the topology (single node, reference architecture or multi-node) and how much maintenance window your change process allows. Each hop also needs a backup and a restore test. Ask the vendor or partner to show the migration status for your instance and to base the timeline on a rehearsal in a copy of production, not on a generic estimate.
Can our own team run the upgrade without a partner?
Yes, if your team has Linux administration, PostgreSQL and Redis experience, a tested backup and restore process, and time to read the upgrade notes for every stop. Teams that have not upgraded GitLab for several releases usually find the work is the research and rehearsal rather than the commands. A partner adds value when the instance is several versions behind, runs in a regulated environment with change approvals, or needs zero-downtime procedures across multiple nodes. Decide by comparing your staff's capacity and past upgrade records with the list of hops and risks in the written plan.
What skills and time do our staff need to provide?
Plan for at least one administrator who owns the upgrade end to end, a database owner who checks migrations and backups, and someone who manages Runners and any integrations. Staff also need time for change reviews, test sign-off by the teams that use GitLab, and access to the hosts, object storage and load balancers. Ask your provider which of these roles they expect you to fill, and whether they need access to production logs, the Admin area and the database during each hop.
Can we skip a required upgrade stop?
No. GitLab requires upgrades to pass through the required stops at x.2, x.5, x.8 and x.11, so an instance several versions behind must step through each one in order. Skipping a stop can leave the database schema or background migrations in a state the next release does not expect. The practical question is which stops apply to your current version and which patch releases to use at each stop. Confirm the full sequence in the GitLab upgrade paths documentation before you schedule any hop.
What happens to our Runners and integrations during the upgrade?
GitLab documents that Runner major and minor versions should match the GitLab server, so Runners usually need an upgrade plan of their own. The chart-based and multi-node procedures may upgrade Runners in a specific order. Integrations such as chat, issue trackers, secrets managers and Kubernetes clusters need a review at each stop because API behavior, token types and authentication settings can change. Inventory every Runner, executor type and integration before the first hop, and test each one against the next version in a rehearsal environment.
How does the GitLab 20.0 release affect upgrade planning?
GitLab 20.0 is planned for May 2027, and GitLab ships a major release yearly. Because the 19.x line has its own required stops, the 20.0 plan should start with the current version and the stops that remain before 19.x is complete. Items to clear before 20.0 include retiring Docker Machine runners and checking Elasticsearch and dependency scanning dependencies. Schedule a review against the maintenance policy and the release notes as the date approaches, and confirm the 20.0 requirements with GitLab before setting any deadline.
How DeployOpen scopes and delivers a GitLab upgrade
DeployOpen plans, implements, backs up, upgrades, documents and supports self-hosted GitLab inside your own infrastructure, whether that is your cloud accounts, data centers or an air-gapped network. For an upgrade that spans several versions, the first deliverable is a written plan: the current version, the required stops your path must pass through, the background migrations that must show Finished before each hop, and the backup and rollback point taken before every stop. That plan is what gets scoped, priced and agreed before any change is made to your instance.
Most engagements are fixed-scope, so the written agreement should name the instance and installation method (Linux package, Helm chart, Operator, Docker or source), the number of nodes, any external PostgreSQL, Redis or object storage, the Runner fleet that must be upgraded alongside the server, and the test environment used for rehearsals. Ask whether the scope includes a staging upgrade that follows the same hops as production, the production run, post-upgrade checks and the written record of each stop. Confirm who approves a go or no-go at each stop, and what happens if a background migration does not finish within the window you planned.
Ongoing support, upgrade planning for the next GitLab major release and periodic health reviews are available as a retainer, which suits teams that upgrade on a set cadence rather than once. Confirm with DeployOpen what the retainer covers, how requests are prioritized and which GitLab versions it includes, and agree those terms in writing like any other scope. DeployOpen prepares systems and evidence for your change management and audit processes, but it does not issue audit reports or certifications; independent auditors and certification bodies do that work.
