GitLab 18.0, our next major release, will be packed with new features that push the boundaries of DevSecOps innovation. At the same time, we’ll be removing some deprecated features from GitLab. Here is what you need to know about these breaking changes and how you can mitigate their impact.
Deployment windows
GitLab.com
Breaking changes for GitLab.com will be limited to these three windows.
- April 21-23, 2025
- April 28-30, 2025
- May 5-7, 2025
Many other changes will continue to roll out throughout the month. You can learn more about the high-impact changes occurring within each of these windows in this breaking changes documentation.
Note: Breaking changes may fall slightly outside of these windows in exceptional circumstances.
GitLab Self-Managed
GitLab 18.0 will be available starting on May 15. You can learn more about the release schedule here.
GitLab Dedicated
The upgrade to GitLab 18.0 will take place during your maintenance window from June 24-29, 2025. You can learn more and find your assigned maintenance window here.
We’ve also developed custom tooling and resources to help you assess the impact of these changes on your environment and plan any necessary actions ahead of the 18.0 upgrade. You can find information about these mitigation tools and resources, including GitLab Detective, below.
Visit the Deprecations page to see a full list of items scheduled for removal in 18.0. Read on to learn what’s coming and how to prepare for this year’s release based on your specific deployment.
Breaking changes
High impact
1. CI/CD job token - “Limit access from your project” setting removal
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) for added security. This setting was called Limit CI_JOB_TOKEN access. In GitLab 16.3, we renamed this setting 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 significant 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
2. CI/CD job token - Authorized groups and projects allowlist enforcement
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 GitLab 17.6, administrators for GitLab Self-Managed and Dedicated instances have had the option to enforce a more secure setting for all projects, which 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
3. Dependency Proxy token scope enforcement
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 upgrading, 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.
Medium impact
1. New data retention limits for vulnerabilities on GitLab.com
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
2. Reject container image pull policies not in allowed_pull_policies
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.
3. PostgreSQL 14 and 15 no longer supported
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 version of PostgreSQL.
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 example, 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 sufficient disk space to accommodate the upgrade.
4. Deprecate the Terraform CI/CD templates
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.ymlTerraform.latest.gitlab-ci.ymlTerraform/Base.gitlab-ci.ymlTerraform/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 the 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, however, Issue #415638 proposes adding this feature. If CI/CD components become available on GitLab Self-Managed, the OpenTofu CI/CD template will be removed.
Read more about the new OpenTofu CI/CD component.
5. Major update of the Prometheus subchart
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.
Low impact
1. No longer building SUSE Linux Enterprise Server 15 SP2 packages
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.
2. Remove Gitaly rate limiter
Self-Managed
Gitaly used to support RPC-based rate limiting. We are deprecating this feature as it does not achieve the desired results. Please see the deprecation issue for details.
If customers have the rate limiter configured (which is being deprecated), no error will be returned and the config will simply be ignored.
Customers should utilize the Concurrency Limiter instead.
3. Deprecate NGINX controller image 1.3.1 support
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 need to add the RBAC rules before migrating to 1.11.2 or later. 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. Users who manage their own RBAC can set this to true to enable their deployments to also use 1.11.2, after ensuring the new RBAC rules are in place.
We plan 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 use only 1.11.2, which offers numerous security benefits.
4. Application Security Testing analyzers major version update
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. After GitLab 18.0, all newly fixed bugs and 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 to the latest three minor releases.
5. API Discovery will use branch pipelines by default
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 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.
6. DAST DAST_DEVTOOLS_API_TIMEOUT will have a lower default value
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 to which it applies.
Tools and resources to manage your impact
We’ve developed specific tooling to help our customers understand how these planned changes impact their GitLab instance(s). 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.
- 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.
We’ve also launched a series of micro courses (15 minutes or less!) on GitLab University to help you plan and execute mitigation activities for several of these changes. Start your learning journey here.
If you have a paid plan and have questions or require assistance with these changes, please open a support ticket on the GitLab Support Portal.
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.
