What upgrades and support involve for GitLab
GitLab ships a major release once a year, a minor release on the third Thursday of each month, and patch releases twice a month. Under its maintenance policy, bug fixes are backported only to the current stable release, while security fixes also go to the previous two monthly releases. That means the window for receiving a fix without moving to a newer version is short, and an instance that falls behind the supported releases is exposed. Before you plan any work, confirm which releases your instance runs and which release line you intend to stay on.
Upgrade work is usually triggered by one of four situations: the instance has fallen behind the supported releases, a security advisory affects your version, a planned move requires a newer version, or the team no longer has the capacity to read release notes for each release. The last trigger is the most common reason teams stop upgrading on time. Upgrades that cross a required upgrade stop, which GitLab documents at versions x.2, x.5, x.8 and x.11 since 17.5, must pass through each stop in order, so a long gap turns a routine patch into a multi-stop catch-up with its own backups and checks at every step.
Most teams with a platform engineer and a regular maintenance window can run routine patch and minor upgrades in-house, provided they read the upgrade path documentation and the release notes before each change and take a verified backup first. Partners are usually brought in for the multi-stop catch-up, for multi-node or high availability upgrades where the order of database, Gitaly and application node changes matters, for air-gapped instances where packages must be staged offline, and for recurring support that covers upgrade planning, testing and on-call response. Ask any partner to state in writing which upgrade types are covered and which are priced separately.
What the work includes
The upgrade work is delivered as a sequence of checked steps, each with a written output. Ongoing support covers the release cadence between planned upgrades.
Upgrade assessment
We compare your current GitLab version against the supported release lines and identify every required upgrade stop between it and your target, such as the x.2, x.5, x.8 and x.11 releases. We also review your installation method, component versions, background migration status and any custom configuration that could affect the path.
Written upgrade plan
The plan sets out the stop sequence, the expected change at each stop, the checkpoints where a rollback is possible and the conditions that trigger a rollback. It also names who approves each stop and which maintenance windows the work requires. You review and sign the plan before any change is made.
Pre-upgrade backups
We take a backup with the gitlab-backup tool and save the secrets file and configuration files, including gitlab.rb, separately from the backup archive. Missing secrets can make restored data unreadable, so we confirm the copies are complete and stored outside the instance before any upgrade step starts.
Staged execution on a copy
Every stop is first run on a non-production copy built from a recent backup. This shows how long each step takes on your data, surfaces failed background migrations and proves the rollback steps work. Findings from the copy update the production plan before it is executed.
Production execution and verification
We run each stop in production according to the approved plan and verify health after each one, including service status, background migration progress and application logs. Verification steps are recorded against the checklist so you can see the state of the instance at every stop.
Post-upgrade checks
After the final stop we check that GitLab Runners are connected and on versions aligned with the GitLab release, that integrations such as webhooks and chat connections still deliver, and that sign-in works through your configured authentication providers. Users are asked to confirm access before the change is closed.
Runbook for the next cycle
We document the upgrade as a runbook your team can follow at the next required stop, covering commands, expected output, known issues found during the work and the rollback path. The runbook is written so an engineer who did not run this upgrade can carry out the next one.
Ongoing support retainer
Ongoing support is offered as a retainer and covers patch review against the maintenance policy, scheduled minor upgrades, triage of security advisories that affect your version and alignment of Runner versions with the GitLab release. The scope, response expectations and review cadence are agreed in writing before the retainer starts.
What drives cost and duration
This table lists the scope factors that change the effort of a GitLab upgrade and ongoing support, why each one matters, and what to do to keep it under control.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Version gap and required upgrade stops | GitLab requires upgrades to pass through required stops at x.2, x.5, x.8 and x.11, so a distant version means several sequential upgrades, each with its own checks and rollback point. | Upgrade regularly within the supported window and ask the partner to map the exact stop sequence from your current version before quoting. |
| Number of upgrade stops to pass through | Each stop is a separate upgrade cycle with background migrations to watch, so the count multiplies testing and maintenance windows. | Plan the stops as milestones with a fixed test pass for each one, and confirm the count with the upgrade paths documentation for your version. |
| Installation method | The Linux package, Helm chart, GitLab Operator, Docker and source installs each have their own upgrade mechanics, and mixing methods or moving between them adds migration work. | Standardize on one method and document the deployment as code so each upgrade follows the same runbook. |
| Single node or multi-node reference architecture | Multi-node setups need zero-downtime upgrade sequencing across application, Gitaly and database components, which takes more planning and rehearsal than a single node. | Match the reference architecture to your user count and rehearse the rolling sequence on a staging copy before production. |
| Number of runners and executor types | Runners must stay aligned with GitLab major and minor versions, and each executor type (shell, Docker, autoscaling) needs its own compatibility check. | Use a small number of executor standards, keep runner versions aligned in the same upgrade plan, and automate runner updates. |
| Geo or other secondary sites | A Geo secondary site must be upgraded and verified alongside the primary, so every upgrade step is repeated and checked on each site. | Confirm replication health before each upgrade and include the secondary in the test environment and change calendar. |
| External PostgreSQL, Redis and Gitaly components | External services are upgraded on their own schedules and must stay within GitLab's supported versions, so the team coordinates more change windows. | Document the supported versions for each external component in the upgrade plan and test them together. |
| Customizations in gitlab.rb and through the API | Custom settings, scripts and API integrations can break at a stop or after a background migration, and each one needs regression testing. | Keep configuration in version control, list every custom integration, and include them in the post-upgrade test suite. |
| Air-gapped networks | Packages and container images must be transferred by hand, verified and staged before each upgrade, which adds lead time and handling steps. | Mirror the required packages and images for each stop in advance and keep a transfer checklist per release. |
| Tier in use (Free, Premium or Ultimate) | Features such as Geo, advanced CI/CD, priority support and security and compliance features depend on the tier, so tier-specific functions must be tested after each upgrade. | Confirm which features are licensed and enabled, and test only those in the regression suite. |
| Number of environments to test | Each environment such as development, staging and production repeats the upgrade and verification, so the count directly multiplies effort. | Limit the environments to what is needed for risk, and ask for the environment count in any quote. |
How an upgrade project runs
The phases of a GitLab upgrade project move from an accurate inventory to a tested path, a rehearsed production change and a handover the internal team can operate.
Inventory the installed version and layout
We record the running GitLab version, the installation method (Linux package, Helm chart, Operator, Docker or source), the component layout, and every integration and runner that depends on the instance. Your team confirms access and any offline or air-gapped constraints. The output is a written inventory that both sides sign off before any path is designed.
Design the required upgrade path
Using the current GitLab upgrade paths documentation and the maintenance policy, we list each required upgrade stop and its target release, then check those targets against the lines GitLab currently supports. The output is a stop-by-stop path with the reason for each stop, which becomes the basis for the rehearsal and the production plan.
Prepare the environment and rehearse on a copy
We build a copy of the instance from production data and walk the full upgrade path on it, one stop at a time. Each stop is timed against the change window agreed in the written scope, and any failed step, configuration drift or integration break is logged and fixed before production. The output is a rehearsal record and a corrected runbook.
Verify backups and a restore
Before any production change, we confirm a current backup of the database, repositories, uploads and object storage, and that the secrets and configuration files are saved separately. We restore that backup to a separate host and check that repositories, merge requests and CI data open correctly. The output is a restore report that names the backup, the restore host and the result.
Execute production with a checkpoint at each stop
We run the upgrade in production one required stop at a time. After each stop we check the application health, the version reported by the instance and the state of background migrations before moving on. If a checkpoint fails, the change halts at that stop and the agreed rollback path applies. The output is a checkpoint log for every stop.
Validate after the upgrade
We confirm that background migrations have completed, that no migration errors remain in the logs, and that the Runner fleet is on a version aligned with the GitLab release. Integrations such as SSO, webhooks and artifact stores are tested with real traffic. The output is a validation checklist signed off by your team.
Hand over the runbook and support calendar
We deliver the runbook for the upgrade and for future stops, the rollback procedure, and a support calendar that tracks monthly minor releases, patch releases and the next required stop. Your engineers are walked through the runbook. The output is a documented handover and, if you choose a retainer, a written support scope for the next cycle.
What usually goes wrong
Most GitLab upgrade problems come from a small set of repeatable mistakes in sequencing, testing and version alignment. Each card names the failure and the check that prevents it.
Skipping a required upgrade stop
GitLab requires upgrades to pass through stops at x.2, x.5, x.8 and x.11 since GitLab 17.5, for example 18.5, 18.8 and 19.2. Jumping directly past one of these can leave the database schema and background work in a state the next release cannot read. Before each change, check the upgrade paths documentation and write the full sequence of stops into the change plan.
Leaving background migrations unfinished
Some schema and data changes run as background migrations after the application restarts, and they can take far longer than the upgrade window. Moving to the next required stop before they finish can block the upgrade or corrupt data. Check the pending migration count in the admin area and wait for it to reach zero before continuing.
Treating untested backups as recoverable
A successful backup job does not prove that GitLab can be restored. Backups also need the secrets and configuration files saved separately, and restores often fail on those gaps. Run a restore into a separate environment at the target version, confirm repositories, CI data and logins work, and repeat this on a schedule.
Runners drifting from the GitLab version
GitLab Runner is distributed separately from the GitLab server, and the documentation advises keeping its major and minor versions aligned with GitLab. When the server moves ahead and runners stay behind, jobs can fail after the upgrade with errors that look unrelated to the change. Inventory every runner fleet, including autoscaled and Kubernetes runners, and upgrade them in the same change window.
Falling out of the maintained release set
The maintenance policy lists which releases are maintained, and bug fixes are backported only to the current stable release, while security fixes also reach the previous two monthly releases. An instance that falls behind this set may need a much larger jump to receive a security fix. Check the maintenance policy each cycle and schedule upgrades before a release leaves the maintained list.
Late patches in air-gapped environments
Isolated networks receive offline packages and images through a manual transfer, so each patch can arrive days or weeks after release. Teams then batch several releases together and skip required stops or fall out of maintenance. Agree on a transfer cadence, keep a verified copy of each package, and confirm the offline procedure in the air-gapped installation guidance.
Configuration changes that break on upgrade
Custom settings in gitlab.rb, environment variables and reverse proxy files often outlive the release they were written for. A renamed or removed setting can stop services from starting after the upgrade. Keep these files in version control, diff them against the new release's defaults before each change, and review the release notes for deprecations.
Upgrading Geo or HA nodes out of order
Multi-node deployments with high availability or Geo secondary sites must be upgraded in an order that keeps components compatible during the rolling change. Upgrading the primary and secondary sites, or application nodes and database nodes, in the wrong sequence can break replication or cause outages. Write the node order in the runbook, rehearse it in a non-production environment, and confirm replication health between steps.
Recurring costs after go-live
This table lists the costs that keep arriving after a self-managed GitLab goes live, what recurs for each, and what to confirm before budgeting.
| Cost item | What recurs | What to confirm |
|---|---|---|
| Subscription edition | Free has no license fee. Premium is listed at 29 US dollars per user per month billed annually on the GitLab pricing page. Ultimate is custom priced. | Check current figures on the GitLab pricing page before budgeting. Confirm the tier that covers the features you need, and ask GitLab for Ultimate pricing in writing. |
| Test and staging infrastructure | Servers or cloud capacity for a non-production copy that receives each monthly minor release and patch before production. | Confirm the copy is sized to match production architecture, and who pays for it in your accounts or data centers. |
| Backup storage and restore tests | Object storage and PostgreSQL backup retention that grows with data, plus recurring time to run restore tests and record results. | Confirm retention periods, storage growth per year and how often your team will perform a full restore test. |
| Runner compute | Build capacity for CI/CD jobs, including autoscaling capacity on your cloud or hypervisor, which scales with pipeline volume. | Confirm peak job concurrency, executor type and whether idle runner capacity is billed in your environment. |
| Monthly and patch release cycle | Internal admin time each month for the third Thursday minor release, plus patch releases twice a month, including staging validation and rollout. | Confirm which staff own the cycle, how many hours they can allocate, and whether maintenance windows must be scheduled with users. |
| Required upgrade stops | Planned multi-step upgrades at x.2, x.5, x.8 and x.11 releases, each needing a rehearsal on staging and a rollback plan. | Confirm the upgrade path from your current version against the GitLab upgrade paths documentation before each stop. |
| Support retainer | Recurring fee for ongoing support, upgrades and monitoring if you buy a retainer from a partner. Coverage depends on the written scope. | Ask DeployOpen for a quote from the written scope. DeployOpen does not publish prices. Confirm response expectations and what is excluded. |
| Internal skills | Staff time to read release notes, assess security patches, and follow the upgrade and recovery runbook as the platform changes. | Confirm who holds each runbook step, how often training is refreshed, and whether a backup administrator is named. |
How the work differs by starting point
A single-node Linux package installation on a recent release is usually the most direct upgrade path, but it still follows the required upgrade stops and the current release line. The planning centers on the version gap and a complete backup taken before any change.
- Version gap: confirm the installed version against the upgrade paths documentation and identify the next required stop, even if the gap looks small.
- Backup and rollback: take a full gitlab-backup and save the secrets and configuration files separately. Confirm with your vendor which restore steps are tested for your version.
- Maintenance window: a single node has no redundancy, so plan downtime for the full upgrade, including background migrations that may run after the package update.
- Verification: check the instance health tools and key workflows such as clone, push, merge requests and pipelines after each stop.
- Operations: confirm your patch cadence against the maintenance policy so the next upgrade is a short one.
A long-lagging installation needs several required upgrade stops in sequence, and each stop has its own migrations, backups and verification. The work is planned as a chain of checkpoints rather than one upgrade.
- Stop map: list every required stop between your current version and the target, and confirm the order with the upgrade paths documentation for your exact versions.
- Checkpoints: take a backup and run health checks before each stop, so a failure leaves a known state to return to.
- Background migrations: confirm with your vendor how long-running background migrations should be allowed to finish before the next stop begins.
- Compatibility: review runner, integration and API client versions against each intermediate release, because they may need to change along the way.
- Time: ask your vendor to state the number of stops and the verification effort for each, since duration depends on your data volume and configuration.
A multi-node or high availability deployment needs zero-downtime planning, with each component handled separately because the order of changes affects availability. Reference architectures for 3,000 users or more generally use Gitaly Cluster with Praefect, PostgreSQL with Patroni, Redis Sentinel and Consul.
- Gitaly: confirm the upgrade order for Gitaly nodes and Praefect with your vendor, and verify repository replication health before and after each step.
- PostgreSQL: confirm how Patroni handles switchover and replica state during the upgrade, and verify replication lag before moving on.
- Redis: confirm the Sentinel behavior during node restarts and how failover is tested.
- Application nodes: confirm the rolling order and load balancer drain behavior so traffic stays on upgraded and non-upgraded nodes in a supported mix.
- Verification: test failover in a non-production copy first and record the results for the change record.
A Helm chart or Operator deployment changes the upgrade sequence because stateful services sit outside the cluster under the Cloud Native Hybrid layout. The GitLab reference architecture documentation says PostgreSQL and Redis inside Kubernetes are not supported, so those services are upgraded through their own platforms.
- Layout check: confirm which services run in the cluster and which run on VMs or managed services, and plan each group's upgrade separately.
- Chart and Operator versions: confirm the compatible chart or Operator version for each GitLab release with your vendor before changing either.
- External services: plan PostgreSQL, Redis and Gitaly upgrades on their own schedules and verify connectivity from the cluster afterward.
- Configuration: review values files and secrets for each intermediate version, since they can change between releases.
- Rollback: confirm how Helm release history and database backups work together if a rollback is needed.
An air-gapped installation moves packages and images into an isolated network and reviews patches offline. The upgrade plan starts with transfer and review, and the vendor should confirm the exact artifacts needed for each target release.
- Artifact transfer: plan how packages and container images are validated, transferred and imported, and confirm the required artifacts with your vendor for each target version.
- Patch review: schedule offline review of monthly and patch releases, since security fixes can be backported to more than one release line.
- Dependencies: confirm which scanners and Duo Self-Hosted features need separate offline guidance and what updates they require.
- Licensing: confirm how license activation works without internet access before the target release is staged.
- Verification: test the transferred artifacts in a staging enclave before they are used in production, and record the checksums in the change record.
An installation with Geo needs the secondary site to follow the primary, so every upgrade is planned for both sites together. Geo is available in the Premium and Ultimate tiers and provides a warm-standby secondary in another region.
- Version alignment: confirm with your vendor the supported version difference between primary and secondary during the upgrade, and the order in which the two sites change.
- Replication: verify that replication and verification status are healthy on the secondary before and after the primary is changed.
- Failover readiness: confirm that the secondary can still be promoted after the upgrade, and test this in a non-production environment.
- Backups: confirm backup responsibilities for each site, since the secondary is not a substitute for a tested restore.
- Operations: plan the window for both sites and confirm how monitoring alerts are handled while replication catches up.
What you need to provide
Before a fixed-scope upgrade or support quote can be written, the team needs a precise picture of the instance as it runs today. Start with the current GitLab version and installation method, since the Linux package, Helm chart, Operator, Docker and source installs each change the upgrade steps. Send the gitlab.rb file, gitlab-secrets.json, and any other configuration files you have changed, with secrets redacted but keys and structure intact. Include the node layout or the reference architecture you run, and state whether PostgreSQL, Redis and Gitaly are bundled or external.
Provide a list of runners with their executors, versions and tags, and name the owner of each integration that calls GitLab, such as your identity provider, Jira, chat, artifact stores and webhook consumers. Confirm which tier you use (Free, Premium or Ultimate), because feature checks and Geo or high availability options depend on it. If the install is air-gapped, document the network constraints, how packages and container images reach the environment, and who transfers them. Give access to a non-production copy that can be restored from production data, and to the production change window with its approval rules.
Confirm that a restore-capable backup exists and is stored outside the GitLab host. Ask the operations team to run a restore test on a separate host before scoping, and record how long it took. Name one decision maker who approves each stop, including the go or no-go at each required upgrade stop and any background migration that must finish first. Name who signs off the post-upgrade check, and who receives incidents during the window. Agree the escalation path, the on-call contacts and the rollback decision owner in writing before the window opens.
Frequently asked questions
How much does a self-managed GitLab upgrade cost?
The cost follows the written scope, so no single figure applies to every instance. The main drivers are the number of required upgrade stops between your current and target versions, the number of environments to test in, the architecture (single node, Linux package with multiple nodes, or Kubernetes), the integrations and customizations that need regression testing, and whether the instance runs in an air-gapped network. A fixed-scope project is a one-time cost. Ongoing support, scheduled upgrades and continuous testing are separate retainers that recur. Ask any partner for a quote that lists stops, environments, nodes, test coverage and handover documents.
How long does a GitLab upgrade take to complete?
Duration depends on the number of required stops, the number of environments, the node count and the size of the data that background migrations must process. Each stop is a separate step with its own backup, upgrade, health check and verification, so a long path takes longer than a single jump. Multi-node setups add sequencing work for each component. Do not plan from a generic estimate. Ask for a timeline in the written scope that shows each stop, the staging runs, the change windows you must approve and the point at which production cutover happens.
Can our own team upgrade GitLab without outside help?
Many teams upgrade GitLab on their own, and GitLab publishes the documented steps for each version. Your team can keep ownership of backups, maintenance windows, runner version alignment and routine patch releases. A second pair of eyes is most useful when planning the upgrade path, running the first upgrade on a multi-node or Kubernetes setup, testing integrations in staging, and writing the rollback plan. Check whether your team has done a recent staging upgrade and a restore test. If not, the gap is the part to close before the production change.
How do required upgrade stops and security patches affect older GitLab versions?
Required upgrade stops and patch timing both penalize instances that fall behind. Since GitLab 17.5, upgrades must pass through versions x.2, x.5, x.8 and x.11, such as 18.2, 18.5, 18.8 and 18.11, so a jump that skips a stop can leave the instance off the supported path. GitLab backports bug fixes only to the current stable release, but security fixes also reach the previous two monthly releases. An instance further behind receives no backported security fix and must climb several stops before taking current patches. Plan the path with GitLab's upgrade paths documentation before each cycle.
Can a multi-node GitLab be upgraded with zero downtime?
A multi-node setup can be planned for zero downtime, but it is not automatic. The result depends on your reference architecture, the load balancers and components in front of the application, the background migrations in each release on your path, and what GitLab documents for each version. Single-node installs usually need a maintenance window. The docs generally recommend a high availability strategy from 3,000 users. Confirm with GitLab for your exact architecture, version and path, and rehearse the node-by-node sequence in staging before you promise users anything.
What does ongoing GitLab support cover, and what must we provide?
A fixed-scope upgrade project ends with a documented handover. A retainer adds ongoing support, scheduled upgrades and continuous testing, and the written agreement defines which of these it includes. GitLab's own priority support is listed on its pricing page as a feature of the Premium tier, which is a separate contract from any DeployOpen retainer. You will need to provide access to the infrastructure accounts, a staging environment, backup and restore data, change windows, named approvers, and an inventory of runners and integrations. Confirm response expectations in writing before you sign.
How DeployOpen works on this
DeployOpen plans, performs and hands over GitLab upgrades inside your own infrastructure, from the required upgrade stops through to the post-upgrade checks your team needs. Ongoing support can be run as a retainer after the handover.
How we scope
- Confirm your current GitLab version and map the required upgrade stops at x.2, x.5, x.8 and x.11 to your target release.
- Record your installation method, whether Linux package, Helm chart, Operator or Docker, and whether you run a multi-node setup.
- Agree the written scope in advance, covering the upgrade path, environments, runner and integration checks, and any support period. Engagements are fixed-scope.
How we build
- Take and verify a full backup and copy the secrets and configuration files before any change touches the instance.
- Rehearse the upgrade on a staging copy, including background migration status checks and a review of the release notes for your configuration.
- For multi-node setups, plan the rolling sequence and test zero-downtime steps before running them on production.
How we hand over
- Document the upgrade runbook, rollback steps and the version state each environment reached, so your team can repeat it.
- Walk your administrators through post-upgrade checks, including runner version alignment and integration health.
- Deliver a record of configuration changes and open items, and agree which follow-up actions belong to your team.
How we support
- Track GitLab's monthly minor releases and patch releases against your planned upgrade window and flag security fixes for your team.
- Offer ongoing upgrades, patch review and support as a retainer, with the covered activities written into the agreement.
- Confirm with GitLab which of your planned features or tiers, such as Premium or Ultimate, affect the upgrade path before you commit to a schedule.
