Get ready for GitLab 18.0: Breaking change details and mitigations
Description
This year’s major release will introduce new improvements that push the boundaries of DevSecOps innovation. At the same time, we’ll be removing deprecated features from the platform. This article describes the breaking changes expected in GitLab 18.0, tooling to assess your impact, mitigation pathways, and additional resources.
Environment
Impacted offerings:
- GitLab.com
- GitLab Dedicated
- GitLab Self-Managed
Prerequisites
GitLab.com and Dedicated users will automatically receive the upgrade during their specified change windows (see below). Self-Managed users should note that GitLab only supports the current major version and the previous two versions. To continue receiving GitLab Support, please ensure you update to version 16.0 or later.
Solution
For GitLab.com users, any breaking changes will be rolled out over three upgrade windows:
- April 21-23, 2025
- April 28-30, 2025
- May 5-7, 2025
For more information about the specific changes occurring within each of these windows, see Breaking change deployments on GitLab.com. Please note that some breaking changes may fall slightly outside of these windows in exceptional circumstances.
For Self-Managed users, the new version will be made available starting on May 15. To learn more about how to apply the upgrade when ready, see GitLab Releases.
For Dedicated users, the upgrade will take place over one seamless window from June 24 to 29. To learn more about what to expect, see GitLab Dedicated maintenance and release schedule.
We’ve also developed custom tooling and resources that will help you assess the impact of these changes on your environment and plan any actions you need to take ahead of the 18.0 upgrade.
Visit the Deprecations page to see a full list of items scheduled for removal in 18.0. Read on to learn what’s coming, what’s available to you, and how to prepare for this year’s release based on your specific deployment.
CI/CD job token - “Limit access from your project” setting removal (High)
GitLab.com | Self-Managed | Dedicated
In GitLab 14.4, we introduced a setting to limit access from your project's CI/CD job tokens (CI_JOB_TOKEN) to make it more secure. This setting was called Limit CI_JOB_TOKEN access. In GitLab 16.3, we renamed this setting to Limit access from this project for clarity.
In GitLab 15.9, we introduced an alternative setting called Authorized groups and projects. This setting controls job token access to your project by using an allowlist. This new setting is a large improvement over the original. The first iteration was deprecated in GitLab 16.0 and scheduled for removal in GitLab 18.0.
The Limit access from this project setting is disabled by default for all new projects. In GitLab 16.0 and later, you cannot re-enable this setting after it is disabled in any project. Instead, use the Authorized groups and projects setting to control job token access to your projects.
Deprecation notice; GitLab Detective check available
CI/CD job token - Authorized groups and projects allowlist enforcement (High)
GitLab.com | Self-Managed | Dedicated
With the Authorized groups and projects setting introduced in GitLab 15.9 (renamed from Limit access to this project in GitLab 16.3), you can manage CI/CD job token access to your project. When set to Only this project and any groups and projects in the allowlist, only groups or projects added to the allowlist can use job tokens to access your project.
- Prior to GitLab 15.9, the allowlist was disabled by default (All groups and projects access setting selected), allowing job token access from any project.
- Since 17.6, administrators for GitLab Self-Managed and Dedicated instances have had the option to enforce a more secure setting for all projects that prevents project maintainers from selecting All groups and projects. This change ensures a higher level of security between projects.
- In GitLab 18.0, this setting will be enabled by default. On GitLab.com We will automatically populate your projects’ allowlists based on your project authentication logs.
- To prepare for this change on GitLab.com, project maintainers using the job token for cross-project authentication should populate their project's Authorized groups and projects allowlists. They should then change the setting to Only this project and any groups and projects in the allowlist. We encourage the use of available migration tooling to automate the creation of the allowlist based on the project’s authentication logs prior to GitLab 18.0.
- Self-Managed users should populate the allowlists before completing the 18.0 upgrade.
- Dedicated users should work with their GitLab account team to develop the appropriate strategy for their specific instance.
Deprecation notice + Documentation; GitLab Detective check available
Dependency Proxy token scope enforcement (High)
GitLab.com | Self-Managed | Dedicated
The Dependency Proxy for containers accepts docker login and docker pull requests using personal, project, or group access tokens without validating their scopes.
In GitLab 18.0, the Dependency Proxy will require both read_registry and write_registry scopes for authentication. After this change, authentication attempts using tokens without these scopes will be rejected.
Before you upgrade, create new access tokens with the required scopes, and update your workflow variables and scripts with these new tokens.
You also have the option to use Dependency Token Checker, a community-developed script that allows you to view tokens and rotate them automatically.
New data retention limits for vulnerabilities on GitLab.com (Medium)
GitLab.com Ultimate tier customers only
Starting in GitLab 18.1 with a phased six-month rollout, we will be introducing a new data retention limit for GitLab.com Ultimate customers to improve system performance and reliability. The data retention limit affects how long your vulnerability data is stored.
Vulnerabilities older than 12 months that have not been updated will be automatically moved to cold storage archives. These archives:
- Remain accessible and downloadable through the GitLab UI
- Are retained for 3 years
- Are permanently deleted after 3 years
Deprecation notice + Documentation
Reject container image pull policies not in allowed_pull_policies (Medium)
GitLab.com | Self-Managed | Dedicated All configured pull-policies should be present in the allowed_pull_policies configuration specified in the runner's config.toml file. If they are not, the job should fail with an incompatible pull policy error.
In the current implementation, when multiple pull policies are defined, jobs pass if at least one pull policy matches those in allowed-pull-policies, even if other policies are not included.
In GitLab 18.0, jobs will fail only if none of the pull policies match those in allowed-pull-policies. However, unlike past behavior, jobs will use only the pull policies listed in allowed-pull-policies. This distinction can cause jobs that currently pass to fail in GitLab 18.0.
Deprecation notice + Documentation
PostgreSQL 14 and 15 no longer supported (Medium)
Self-Managed
GitLab follows an annual upgrade cadence for PostgreSQL.
Support for PostgreSQL 14 and 15 is scheduled for removal in GitLab 18.0. In GitLab 18.0, PostgreSQL 16 becomes the minimum required PostgreSQL version.
PostgreSQL 14 and 15 will be supported for the full GitLab 17 release cycle. PostgreSQL 16 will also be supported for instances that want to upgrade prior to GitLab 18.0.
To prepare for this change, on instances that don't use PostgreSQL Cluster (for instance, if you are running a single PostgreSQL instance you installed with an Omnibus Linux package), upgrades to GitLab 17.11 will attempt to automatically upgrade PostgreSQL to version 16. If you use PostgreSQL Cluster or opt out of this automated upgrade, you must manually upgrade to PostgreSQL 16 to be able to upgrade to GitLab 18.0. Make sure you have enough disk space to accommodate the upgrade.
Deprecation notice + Documentation + Migration Guidelines
Deprecate the Terraform CI/CD templates (Medium)
Self-Managed
The Terraform CI/CD templates are deprecated and will be removed in GitLab 18.0. This affects the following templates:
- Terraform.gitlab-ci.yml
- Terraform.latest.gitlab-ci.yml
- Terraform/Base.gitlab-ci.yml
- Terraform/Base.latest.gitlab-ci.yml
GitLab won't be able to update the terraform binary in the job images to any version that is licensed under BSL.
To continue using Terraform, clone the templates and Terraform image, and maintain them as needed. GitLab provides detailed instructions for migrating to a custom built image.
As an alternative we recommend using the new OpenTofu CI/CD component on GitLab.com or the new OpenTofu CI/CD template on GitLab Self-Managed. CI/CD components are not yet available on GitLab Self-Managed, but Issue #415638 proposes to add this feature. If CI/CD components become available on GitLab Self-Managed, the OpenTofu CI/CD template will be removed.
You can read more about the new OpenTofu CI/CD component here.
Major update of the Prometheus subchart (Medium)
Self-Managed
With GitLab 18.0 and GitLab chart 9.0, the Prometheus subchart will be updated from 15.3 to 27.3.
Along with this update, Prometheus 3 will be shipped by default.
Manual steps are required to perform the upgrade. If you have Alertmanager, Node Exporter or Pushgateway enabled, you will also need to update your Helm values.
Please refer to the migration guide for more information.
No longer building SUSE Linux Enterprise Server 15 SP2 packages (Low)
Self-Managed
Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 15 SP2 ended in December 2024.
Therefore, we will no longer support the SLES SP2 distribution for Linux package installs. You should upgrade to SLES 15 SP6 for continued support.
Remove Gitaly rate limiter (Low)
Self-Managed
Gitaly used to support RPC-based rate limiting. We are deprecating that feature as it doesn’t achieve the desired results. Please see the deprecation issue for full details.
If customers do have the rate limiter configured (that which is being deprecated), no error will be returned and the config will simply be ignored.
Customers should utilize the Concurrency Limiter instead.
Deprecate NGINX controller image 1.3.1 support (Low)
Self-Managed
We're upgrading the default NGINX controller image to 1.11.2. This new version requires new RBAC rules and some users set nginx-ingress.rbac.create: false to manage their own RBAC rules.
These users will have to add the RBAC rules before they migrate to 1.11.2. So we added a fallback mechanism to only deploy 1.3.1 if this Helm value is set as above. We've also added nginx-ingress.controller.image.disableFallback which defaults to false, which users that manage their own RBAC can set to true to make their deployments also use 1.11.2, after they're sure the new RBAC rules are in place.
We want to deprecate the 1.3.1 image support as well as the fallback mechanism as part of 17.5, so that we can remove this support completely and only use 1.11.2 which has many security benefits.
Application Security Testing analyzers major version update (Low)
GitLab.com | Self-Managed | Dedicated
The Application Security Testing stage will be bumping the major versions of its analyzers in tandem with the GitLab 18.0 release.
If you are not using the default included templates, or have pinned your analyzer versions, you must update your CI/CD job definition to either remove the pinned version or update the latest major version.
Users of GitLab 17.0-17.11 will continue to experience analyzer updates as normal until the release of GitLab 18.0, following which all newly fixed bugs and released features will be released only in the new major version of the analyzers.
We do not backport bugs and features to deprecated versions as per our maintenance policy. As required, security patches will be backported within the latest 3 minor releases.
API Discovery will use branch pipelines by default (Low)
GitLab.com | Self-Managed | Dedicated
In GitLab 18.0, we'll update the default behavior of the CI/CD template for API Discovery (API-Discovery.gitlab-ci.yml).
Before GitLab 18.0, this template configures jobs to run in merge request (MR) pipelines by default when an MR is open.
Starting in GitLab 18.0, we'll align this template's behavior with the behavior of the Stable template editions for other AST scanners:
- By default, the template will run scan jobs in branch pipelines.
- You'll be able to set the CI/CD variable AST_ENABLE_MR_PIPELINES: true to use MR pipelines instead when an MR is open. The implementation of this new variable is tracked in issue 410880.
DAST dast_devtools_api_timeout will have a lower default value (Low)
GitLab.com | Self-Managed | Dedicated
The DAST_DEVTOOLS_API_TIMEOUT environment variable determines how long a DAST scan waits for a response from the browser. Before GitLab 18.0, the variable has a static value of 45 seconds. After GitLab 18.0, DAST_DEVTOOLS_API_TIMEOUT environment variable has a dynamic value, which is calculated based on other timeout configurations.
In most cases, the 45-second value was higher than the timeout value of many scanner functions. The dynamically calculated value makes the DAST_DEVTOOLS_API_TIMEOUT variable more useful by increasing the number of cases it applies to.
Verification
We’ve developed specific tooling to help you understand how these planned changes impact your GitLab instance.
Once you’ve assessed your impact, we recommend reviewing the mitigation steps provided in the documentation to ensure a smooth transition to GitLab 18.0.
If you are running a Self-Managed instance of GitLab 16.X, you can expect additional tooling to assist you with the intermediate migration to 17.0 in the next few weeks. Stay tuned and check back here for updates.
- Advanced Search Deprecations: This tool uses GitLab's Advanced Search API to find strings related to deprecations across GitLab groups and projects. It also reports which files should be manually checked. Note: May have some false positives.
- Dependency Scanning Build Support Detection Helper: This tool identifies projects impacted by three Dependency Scanning deprecations (1, 2, 3; all postponed to 19.0). It uses API to scan for relevant files and CI job names.
- GitLab Detective (Self-Managed only): This experimental tool automatically checks a GitLab installation for known issues. It completes complex checks by looking at config files or database values. Note: Needs to run directly on your GitLab nodes.
Additional Information
- If you have a paid plan and have questions or require assistance with these changes, please open a Support Ticket.
- If you are a free Gitlab.com user, you can access additional support through community sources, such as GitLab Documentation, GitLab Community Forum, and Stack Overflow.