Preparing self-managed GitLab for the 20.0 release: what to clear first
If your self-managed GitLab instance must reach 20.0, start by clearing three components and mapping the stops you must pass through first. GitLab plans GitLab 20.0 for May 2027, and the items scheduled or proposed for removal in that release are the Docker Machine executor, Gemnasium-based dependency scanning and Elasticsearch 7.x support for advanced search. This page is a planning page: it tells you what to inventory and decide now, not a procedure to run on the day. GitLab ships a major release once a year, a minor release on the third Thursday of each month and patch releases twice a month. The maintenance policy currently covers 19.5, 19.4 and 19.3, and bug fixes reach only the current stable release, so a version that falls out of that window will not receive routine fixes. Your path to 20.0 runs through the 19.x required upgrade stops at 19.2, 19.5, 19.8 and 19.11, which the GitLab upgrade paths documentation sets out. Work backward from those stops and confirm the current stop list against that page before you commit a schedule.
Because the removals are scheduled or proposed, confirm their status with GitLab before you act on them. Ask which Runner fleet members still use the Docker Machine executor, which projects rely on Gemnasium-based dependency scanning and which search clusters still run Elasticsearch 7.x. Each answer determines whether the work is a configuration change, a runner migration or a search cluster upgrade, and each carries a different risk. Record the owner, the cutover window and the rollback path for every item. The GitLab Runner autoscale documentation is the natural starting point for the executor question.
Which GitLab 20.0 removals affect your instance
This table compares the three items planned for removal in GitLab 20.0 and the 19.x required upgrade stops, showing the area each one touches and the action to take. Read each row against the systems you run today, such as runner fleets, scanning pipelines and search indexes. The main takeaway is that the removals are checked in your own environment before May 2027, and the final removal status should be confirmed in the GitLab 20.0 release notes.
| Change | What it affects | Action needed |
|---|---|---|
| Docker Machine executor | Runner fleets that autoscale CI/CD jobs on cloud VMs using the Docker Machine executor | Inventory every runner using this executor, plan a move to a supported autoscaling executor, and confirm the removal status in the release notes |
| Gemnasium-based dependency scanning | Pipelines that rely on Gemnasium-based dependency scanning for vulnerability reports | Identify jobs and templates that call this scanner, test the replacement scanner in a staging project, and confirm the removal status in the release notes |
| Elasticsearch 7.x for advanced search | Search indexes and the cluster that serves advanced search for code and other content | Check the Elasticsearch version in use, plan an index and cluster upgrade path, and confirm supported versions in the advanced search documentation |
| 19.2 required upgrade stop | The path from older 18.x or 19.0 and 19.1 instances to later 19.x releases | Confirm the instance passes through 19.2 before moving further, and check background migrations finish at each stop |
| 19.5 required upgrade stop | The hop from 19.2 toward 19.8 on the way to 20.0 | Plan a maintenance window for this stop and verify backups before the upgrade begins |
| 19.8 and 19.11 required upgrade stops | The remaining hops from 19.5 through 19.11 before 20.0 is reached | Schedule each stop in order, keep runners and components aligned with the server version, and confirm the path in the upgrade paths documentation |
What to inventory and back up before the 19.x stops
Before you move through the 19.x required stops, the work that protects you is a tested backup, a complete list of what runs on your instance and a staging copy to rehearse on. Each item below feeds the next, so a gap in one shows up as a failed upgrade or a broken pipeline later.
Full backup and restore test
Take a fresh backup with the backup task and restore it into a separate environment before any upgrade step. Confirm that repositories, database, uploads and the secrets file restored correctly, because a backup without gitlab-secrets.json cannot decrypt stored CI variables and tokens. Record how long the restore took on your hardware so the downtime window for each stop is based on your own measurement.
Runner and executor inventory
List every GitLab Runner, its version, its executor and the host or cloud account it runs on. Flag any fleet still using the Docker Machine executor, since it is scheduled for removal in GitLab 20.0, and plan its replacement on a supported autoscaling executor. Keep each Runner's major and minor version aligned with the GitLab server it serves.
CI template and scanner job inventory
Search your .gitlab-ci.yml files, shared templates and group-level include files for references to Gemnasium-based dependency scanning. Replace those jobs with the current dependency scanning analyzers before the scanner is removed. Note which projects pull shared templates, because one outdated include can affect many pipelines at once.
Search index and Elasticsearch version check
If advanced search is enabled, record the Elasticsearch or OpenSearch version your cluster runs and confirm it against the advanced search documentation. Elasticsearch 7.x support for advanced search is scheduled for removal in GitLab 20.0, so a cluster on that line needs a planned upgrade or migration. Also record index sizes and the reindexing time you observed, since a full reindex is part of that work.
Staging environment that matches production
Build a staging instance with the same installation method, PostgreSQL and Redis versions, object storage, authentication settings and Runner fleet as production, then restore the latest backup into it. Run each required stop there first and test sign-in, pushes, merge requests and a sample pipeline on every stop. Differences in the staging setup are the most common reason an upgrade rehearsal gives a false result.
How the required upgrade stops shape the 19.x path
GitLab does not let you jump straight to a later release. Upgrades must pass through required upgrade stops, which since GitLab 17.5 fall at versions x.2, x.5, x.8 and x.11. For the 19.x line, those are 19.2, 19.5, 19.8 and 19.11. An instance on an older 19.x version has to step through each stop that applies to it before it moves on, so the first task is to find your current version and list every stop between it and the release you intend to reach. Confirm that list against the upgrade paths documentation for your exact starting version rather than working from memory, because the path depends on where you begin.
The stops matter for support as well as sequencing. GitLab backports bug fixes only to the current stable release, while security fixes also reach the previous two monthly releases. An instance sitting on a version that is no longer in that window receives no fixes for its defects, and the gap widens every month it stays there. Keeping your path anchored on the stops means each hop lands on a version that is still maintained and that GitLab has tested as a valid step. Confirm the currently maintained versions in the maintenance policy before you set the target for each hop, since the list changes with each monthly release.
Build the plan from these facts before you schedule any work. Record the current version, the stops still ahead, the expected order of hops and the point at which each stop must finish, then check background migrations and component prerequisites at each step. Treat the path as a dependency for the 20.0 work: any instance that cannot reach 19.11 or the latest 19.x stop in a reasonable window will face the 20.0 removals on a compressed schedule. Ask your upgrade partner or internal team to confirm the hops, test restores for each stop, and the rollback point before any production change.
Upgrade sequence from 19.x to 20.0
This sequence moves a self-managed GitLab instance from the 19.x line to 20.0 in an order that keeps a verified restore point at every stage. Each step closes with a check, so the team knows whether the instance is ready for the next hop.
Confirm current version and upgrade path
The platform engineering lead records the running GitLab version, the bundled or external PostgreSQL and Redis versions, and the installation method, then maps the remaining hops against the required upgrade stops for the 19.x line, which are 19.2, 19.5, 19.8 and 19.11. Confirm the target sequence against the GitLab upgrade paths documentation before any change is made. The step is done when a written path lists every stop and the operating system and database prerequisites for each one.
Complete all background migrations
The administrator checks the Admin area or the database for batched background migrations and confirms that each one shows Finished before the instance moves to the next stop. Failed or stalled migrations are retried or finalized according to GitLab's documented procedure, and nothing is skipped to save time. The step closes when no migration is pending or failed, which is the precondition for every later hop.
Take and verify a restorable backup
The operator creates a full GitLab backup, together with the configuration and secrets files that the backup procedure does not cover, and stores them outside the instance. A restore is then tested on a separate host to confirm the archive is readable and the data matches. This verified backup is the rollback point for the entire upgrade, and the team should agree in advance that a failed hop means restoring it rather than attempting in-place repair.
Upgrade runners and align versions
The runner owner inventories every GitLab Runner in the fleet and identifies any still using the Docker Machine executor, which GitLab plans to remove in 20.0. Each runner is moved to an autoscaling or Kubernetes-based executor that the team has tested, and all runners are brought to the same major and minor version as the target GitLab release. The step is complete when a test pipeline runs successfully on every runner pool and no job still depends on Docker Machine.
Migrate dependency scanning off Gemnasium
The application security owner finds every pipeline and template that relies on Gemnasium-based dependency scanning and replaces it with the current dependency scanning method documented by GitLab, while noting that feature tier and scanner coverage can differ by language. Scan results are compared against the previous baseline on a sample of projects so that the team can see any gaps before 20.0 removes the old path. The step closes when scans run on the new method and the findings reviewed match expectations.
Move advanced search off Elasticsearch 7.x
The search administrator confirms which Elasticsearch or OpenSearch version backs advanced search and plans a move to a supported version before 20.0, since GitLab plans to remove Elasticsearch 7.x support. The index is rebuilt on the new cluster, and search results for code, issues and merge requests are spot-checked against the old index. The step is done when advanced search serves queries from a supported backend and the old cluster can be decommissioned without loss of search coverage.
Upgrade through each required stop with health checks
The operator upgrades the instance one required stop at a time, starting with 19.2, then 19.5, 19.8 and 19.11, and runs the GitLab health checks, background migration status check, and key workflow tests after each hop. Where the instance runs multiple nodes, the team follows the zero-downtime procedure for each hop rather than improvising. If a hop fails a check, the team stops and restores the verified backup instead of continuing. The step closes when the instance passes every check at 19.11.
Upgrade to 20.0 and confirm the release
After the instance is healthy at 19.11 and the removal items are cleared, the operator upgrades to GitLab 20.0, with the planned release date of May 2027 from the maintenance policy as the target and no assumption that the date is fixed. The team then checks runners, scanning jobs, search and authentication, and confirms that the backup taken earlier is retained until these checks pass. The sequence is complete when 20.0 runs with all pipelines, scans and searches verified and the rollback point is formally released.
How the work differs by installation method and deployment
The Linux package is the installation method most self-managed instances use, and it bundles PostgreSQL, Redis and Sidekiq with GitLab itself. For this topic, that bundling matters because the package performs the database and component updates as part of each upgrade, so preparation focuses on checking the bundled versions, the gitlab.rb settings you have changed and the order of required stops. Work through the upgrade one stop at a time and confirm background migrations finish between stops.
- Bundled components: Check which PostgreSQL and Redis versions the package ships before each hop, and confirm any external database or Redis you run separately is covered by the same plan.
- Configuration drift: Compare your
gitlab.rbandgitlab-secrets.jsonagainst the current templates so custom settings survive the upgrade. - Stop-by-stop sequence: Plan each required stop as a separate change with its own backup and rollback point.
- Runner dependencies: Confirm which runners you still operate use the Docker Machine executor, since that affects the 20.0 work.
- Backup baseline: Take a full backup immediately before each stop and verify it can be restored on a test host.
Confirm the exact package version ladder for your target with the upgrade paths documentation before scheduling changes.
Instances installed with the Helm chart or the GitLab Operator run GitLab components as Kubernetes workloads, so the upgrade is a chart or operator change rather than a package change. The GitLab reference architectures document that stateful components such as PostgreSQL and Redis should not run inside Kubernetes, so most cloud native installs keep those services on VMs or managed services. Preparation therefore covers two sets of change: the chart or operator version mapping and the external stateful services that sit outside the cluster.
- Chart-to-GitLab mapping: Confirm which GitLab version each chart release maps to before choosing a target.
- Runner order: Plan runner upgrades before the server in chart-based upgrades, since runner and GitLab minor versions should stay aligned.
- External stateful services: Verify PostgreSQL, Redis and object storage versions and backups are handled outside the cluster.
- Values files: Reduce custom values to the settings you truly need so the chart upgrade is easier to review.
- Kubernetes version support: Check the cluster version against the chart requirements for your target release.
Confirm the supported topology and any Kubernetes version limits for your target with the installation methods page and the reference architectures documentation.
Self-managed GitLab can run in offline, air-gapped environments, but the upgrade and scanner plan change because packages, container images and vulnerability data must reach the network through an approved transfer process. The GitLab offline documentation includes separate guidance for running GitLab security scanners offline, so scanner work should not be treated as a simple version bump. Plan the transfer of every artifact the upgrade needs before the change window opens.
- Artifact staging: Move packages, images and runner binaries through your approved media process and verify checksums on the inside.
- Scanner data: Confirm how vulnerability databases and scanner components are updated when the network has no outbound access.
- Dependency scanning transition: Check whether any offline job relies on Gemnasium-based dependency scanning, and plan its replacement before 20.0.
- Runner isolation: Confirm runners can reach internal registries and artifact stores without internet access.
- Change evidence: Record each transferred artifact and its verification so auditors can trace the upgrade.
Confirm the offline procedure for each scanner you run with the offline environments page before you commit to a schedule.
Instances serving larger user bases often run multiple nodes for Gitaly, PostgreSQL, Redis and application services, and the reference architectures generally recommend high availability at 3,000 or more users. For this topic, the multi-node layout changes how the required stops are applied, since each hop needs coordinated component updates and a clear load balancer plan. Preparation focuses on sequencing, rollback and whether the HA components themselves are on supported versions for the target.
- Component order: Document which node group upgrades first and how each stop is staged across the cluster.
- Stateful clusters: Confirm Gitaly Cluster with Praefect, PostgreSQL with Patroni, Redis Sentinel and Consul are on versions compatible with each stop.
- Load balancer behavior: Check health checks and drain steps so traffic moves cleanly between nodes.
- Rollback path: Define how you return a node to its previous version if a stop fails.
- Geo sites: If you run a secondary site, plan its upgrade order separately.
Confirm the multi-node sequence and version rules with the reference architectures page before building the change plan.
Single-node instances are the simplest case: one host, one set of services and one backup target. The work is still bounded by the required stops and the 20.0 removals, but the change window is shorter and the steps are fewer. Preparation concentrates on backups, the scanner and runner inventory and a tested restore path rather than on coordinating multiple nodes.
- Downtime window: Expect a full outage during each stop, since no node remains to serve traffic.
- Backup and restore test: Restore the latest backup to a separate host before the first stop.
- Runner inventory: Identify runners on Docker Machine and plan their migration separately from the server.
- Disk and resource checks: Confirm free space for the backup and package download before each hop.
- Scanner review: Identify jobs that depend on Gemnasium-based dependency scanning.
Confirm your current topology against the reference architectures page so you know whether a single-node plan is still appropriate for your user count.
What makes the 20.0 preparation take longer
This table lists the factors that most often stretch the work before GitLab 20.0 and what to measure for each. Use it to size your inventory before asking for a written scope, since the same removals take very different effort depending on how many runners, scanners, indexes and stops your instance carries.
| Effort driver | Why it changes the work | What to measure |
|---|---|---|
| Runners and executor types | Each Docker Machine runner must move to a supported executor, and each fleet needs version alignment with GitLab. | Count runners by executor type, host platform and owning team, and note which ones use autoscaling. |
| Custom scanner pipelines | Pipelines that reference Gemnasium-based dependency scanning need new scanner configuration and updated findings handling. | List every CI template or include that calls dependency scanning, including those inherited from shared project templates. |
| Advanced search index size | Elasticsearch 7.x must be replaced or upgraded, and reindexing time grows with the volume of indexed content. | Record the index size, document counts and the search backend version currently in use. |
| Required upgrade stops ahead | Each stop adds a hop with its own background migrations and post-upgrade checks, so the count of stops ahead sets the length of the sequence. | Confirm your current version and list the x.2, x.5, x.8 and x.11 stops between it and the 20.0 target. |
| Multi-node topology | Zero-downtime steps depend on node roles, load balancer behavior and component order across each node. | Document each node role, the number of application nodes and how traffic is drained during a change. |
| External PostgreSQL or Redis | Database and cache upgrades run outside the bundled procedure and need their own compatibility checks and maintenance windows. | Note the database and Redis versions, hosting model and who controls the change windows for each. |
| Integrations | Chat, secrets managers, Kubernetes clusters and issue trackers each need retesting against the new release. | Inventory every integration, its authentication method and the team that validates it after a change. |
| Offline or air-gapped constraints | Packages, container images, scanner data and runner binaries must be staged inside your network before each step. | Record how artifacts reach the isolated network, how long transfers take in your environment and who approves them. |
Questions teams ask before preparing for GitLab 20.0
What does preparing self-managed GitLab for 20.0 cost?
Cost comes from the people doing the work, not from a license fee for the preparation itself. Your internal team pays in engineer time for inventory, runner changes, scanner replacement and testing, and any partner you bring in is paid for the scope agreed in writing. The cost moves with the number of runners, the number of projects that use Gemnasium-based dependency scanning, the size of your Elasticsearch 7 cluster and how many upgrade stops remain. Licensing is a separate question: GitLab Free costs 0 dollars, Premium costs 29 US dollars per user per month billed annually according to the GitLab pricing page, and Ultimate is custom priced. DeployOpen does not publish a price list, so ask for a quote built from a written scope.
How long does preparation take, and what sets the timeline?
The fixed date is May 2027, when GitLab 20.0 is planned. Working backward, the timeline depends on how far your instance sits behind the 19.x line, since the required upgrade stops at 19.2, 19.5, 19.8 and 19.11 each need a successful hop. Other drivers include how many runners use the Docker Machine executor, how many pipelines call the dependency scanning template, whether Elasticsearch 7.x backs advanced search, and how large the instance is. Change windows and your own release calendar also matter. Ask for a schedule that names each stop and the test environment used before each one.
What does our internal team need to provide?
Your team needs to supply access and decisions that only you can make. Expect to provide:
- A current inventory of GitLab versions, runners, executors and their registration methods
- A list of pipelines and projects that use dependency scanning, plus any scanner output your audit process relies on
- Elasticsearch or OpenSearch details, including whether advanced search is enabled
- Staging or test environments that match production, with a recent backup
- Named owners for change approval, maintenance windows and rollback decisions
Without these, the work stalls at discovery.
Can our team prepare for GitLab 20.0 without a partner?
Many teams can, provided they have engineers who have run GitLab upgrades and CI runners before and time to test in a non-production copy. The hardest parts are usually the required stops, background migrations that must finish before the next hop, and replacing removed components such as the Docker Machine executor without breaking existing pipelines. If your team has none of these skills in-house or cannot take the instance out of normal change flow for testing, a fixed-scope engagement can cover that work. DeployOpen implements, upgrades, documents and supports self-hosted platforms inside your own infrastructure, and it does not issue audit reports.
What happens if an upgrade stop is skipped?
GitLab requires upgrades to pass through the listed stops, so skipping one, for example going from a 19.1 release directly to 19.3, leaves the instance on a path GitLab does not support. The practical result is a failed or incomplete migration, which can block the instance from starting correctly or leave the database in a state that needs recovery. The safe response is to restore from a verified backup taken before the attempt and then run the path again in order. Confirm the exact path for your current version in the GitLab upgrade paths documentation before any change window.
What should a fixed-scope quote for this work include?
A useful quote names the starting version, the target version and each required stop between them. It lists which runners, executors, scanners and search components are in scope, and which environments will be used for testing. It states the deliverables, such as an updated runner fleet, a validated backup and restore check, a rollback plan and a change record for each stop. It also states what is excluded, for example Subversion conversion, Geo secondary sites or work beyond the 20.0 preparation items. Ask for the assumptions about your environment and the acceptance criteria before work begins, since the scope and timelines are agreed in writing.
Do we need to replace Gemnasium-based dependency scanning before 20.0?
Yes, plan for it. The topic facts list Gemnasium-based dependency scanning among items scheduled or proposed for removal in GitLab 20.0, so pipelines that rely on it need a replacement scanning approach. Start by listing every project that includes the dependency scanning template and recording the results your reviewers and auditors use. Then test the replacement on a sample of projects and confirm which GitLab tier provides the scanners you need. The GitLab dependency scanning documentation is the place to confirm current behavior before you commit to a replacement.
Testing and rollback before production
Rehearse every required stop in a staging copy restored from a recent production backup before any change touches production. The goal of the rehearsal is to measure the real sequence on your own data: the number of background migrations that run, how long each hop takes on your hardware, and which steps fail. Restore the backup into an environment with the same GitLab edition, the same operating system, the same PostgreSQL and Redis versions and the same object storage layout as production, then walk the path one stop at a time, such as the 19.2, 19.5, 19.8 and 19.11 stops, confirming each one completes and that batched background migrations show Finished before you move on. Ask your team to record the timings and any manual intervention, because those notes become the production runbook.
After each hop, verify the functions your engineers actually depend on. Confirm that registered GitLab Runners pick up jobs and that a sample pipeline runs to completion, including artifacts and cache. Run the security scanners your policies require and compare their output to the pre-upgrade baseline, paying particular attention to the Gemnasium-based dependency scanning that must be replaced before 20.0. Run representative advanced search queries against the rebuilt index, and confirm that the search backend version still meets the supported range for the target release. Keep a short checklist per hop so a failure is traced to one stop rather than to the whole path.
Roll back from a verified backup when a hop fails in a way you cannot explain within the window you agreed with the business, when data integrity checks disagree with the backup, or when a background migration stays unfinished and cannot be safely retried. Pushing forward is appropriate only when the failure is isolated, understood and reproduced in staging. Test the restore itself, not just the backup job, because a backup you have never restored is a hypothesis. Multi-node topologies and GitLab Geo deployments need extra planning: the order in which Gitaly, application, Sidekiq and database components move must be scripted, and a Geo secondary should be paused at a clean checkpoint so that a disaster recovery copy matches a known state. Confirm both points with the GitLab Geo documentation and your own topology before you schedule the window.
How DeployOpen scopes and delivers a GitLab 20.0 preparation
DeployOpen approaches GitLab 20.0 preparation as a fixed-scope piece of work inside your own infrastructure. We start from your current instance, its runners, scanners and search setup, and the 19.x stops still ahead of you, then agree in writing what gets changed, tested and handed over before the May 2027 release.
How we scope
- Inventory every Docker Machine runner, Gemnasium-based dependency scanning job and Elasticsearch 7 cluster in your instance
- Map your current version against the 19.x required upgrade stops at 19.2, 19.5, 19.8 and 19.11
- Agree the scope, deliverables and timeline in writing before any change is made to your environment
How we build
- Plan replacement executors, scanner configuration and search backend changes as separate, reversible work items
- Test each 19.x upgrade hop in a staging copy of your instance before it touches production
- Verify runner, scanner and advanced search behavior against your own pipelines and projects
How we hand over
- Document the removal items, your decisions and the rollback path for each change
- Record the upgrade order, backup checkpoints and the checks run at every required stop
- Confirm with you which items need vendor or auditor input, since DeployOpen prepares evidence but does not issue attestations
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer once the handover is complete
- Review the 20.0 release notes and patch cadence with your team as new information is published
- Keep the runbooks current as your instance, runners and integrations change after the preparation work
