diff options
Diffstat (limited to 'doc/update')
| -rw-r--r-- | doc/update/deprecations.md | 880 | ||||
| -rw-r--r-- | doc/update/index.md | 226 | ||||
| -rw-r--r-- | doc/update/mysql_to_postgresql.md | 2 | ||||
| -rw-r--r-- | doc/update/package/convert_to_ee.md | 2 | ||||
| -rw-r--r-- | doc/update/package/downgrade.md | 2 | ||||
| -rw-r--r-- | doc/update/package/index.md | 35 | ||||
| -rw-r--r-- | doc/update/patch_versions.md | 4 | ||||
| -rw-r--r-- | doc/update/plan_your_upgrade.md | 12 | ||||
| -rw-r--r-- | doc/update/removals.md | 733 | ||||
| -rw-r--r-- | doc/update/restore_after_failure.md | 2 | ||||
| -rw-r--r-- | doc/update/upgrading_from_ce_to_ee.md | 4 | ||||
| -rw-r--r-- | doc/update/upgrading_from_source.md | 19 | ||||
| -rw-r--r-- | doc/update/upgrading_postgresql_using_slony.md | 2 | ||||
| -rw-r--r-- | doc/update/with_downtime.md | 329 | ||||
| -rw-r--r-- | doc/update/zero_downtime.md | 119 |
15 files changed, 1352 insertions, 1019 deletions
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 903ae9c714c..d726f96f646 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -4,15 +4,7 @@ group: none info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" --- -# Deprecations by milestone - -DISCLAIMER: -This page contains information related to upcoming products, features, and functionality. -It is important to note that the information presented is for informational purposes only. -Please do not rely on this information for purchasing or planning purposes. -As with all projects, the items mentioned on this page are subject to change or delay. -The development, release, and timing of any products, features, or functionality remain at the -sole discretion of GitLab Inc. +# Deprecations by version <!-- vale off --> @@ -38,44 +30,139 @@ For deprecation reviewers (Technical Writers only): {::options parse_block_html="true" /} -View deprecations by the product versions in which they were announced. - -Each deprecation has a **planned removal milestone** and indicates whether it is a breaking change. +In each release, GitLab announces features that are deprecated and no longer recommended for use. +Each deprecated feature will be removed in a future release. +Some features cause breaking changes when they are removed. -Most of the deprecations are **planned for removal in 15.0**, and many of them are **breaking changes**. +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. <div class="js-deprecation-filters"></div> <div class="announcement-milestone"> -## 15.0 +## Announced in 15.1 + +<div class="deprecation removal-160 breaking-change"> + +### Jira GitHub Enterprise DVCS integration + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The [Jira DVCS Connector](https://docs.gitlab.com/ee/integration/jira/dvcs.html) (which enables the [Jira Development Panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/)), will no longer support Jira Cloud users starting with GitLab 16.0. The [GitLab for Jira App](https://docs.gitlab.com/ee/integration/jira/connect-app.html) has always been recommended for Jira Cloud users, and it will be required instead of the DVCS connector. If you are a Jira Cloud user, we recommended you begin migrating to the GitLab for Jira App. +Any Jira Server and Jira Data Center users will need to confirm they are not using the GitHub Enterprise Connector to enable the GitLab DVCS integration, but they may continue to use the [native GitLab DVCS integration](https://docs.gitlab.com/ee/integration/jira/dvcs.html) (supported in Jira 8.14 and later). + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### PipelineSecurityReportFinding name GraphQL field + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +Previously, the [PipelineSecurityReportFinding GraphQL type was updated](https://gitlab.com/gitlab-org/gitlab/-/issues/335372) to include a new `title` field. This field is an alias for the current `name` field, making the less specific `name` field redundant. The `name` field will be removed from the PipelineSecurityReportFinding type in GitLab 16.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### PipelineSecurityReportFinding projectFingerprint GraphQL field + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The [`project_fingerprint`](https://gitlab.com/groups/gitlab-org/-/epics/2791) attribute of vulnerability findings is being deprecated in favor of a `uuid` attribute. By using UUIDv5 values to identify findings, we can easily associate any related entity with a finding. The `project_fingerprint` attribute is no longer being used to track findings, and will be removed in GitLab 16.0. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### REST API Runner maintainer_note + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The `maintainer_note` argument in the `POST /runners` REST endpoint was deprecated in GitLab 14.8 and replaced with the `maintenance_note` argument. +The `maintainer_note` argument will be removed in GitLab 16.0. + +</div> + +<div class="deprecation removal-153"> + +### Vulnerability Report sort by Tool + +Planned removal: GitLab <span class="removal-milestone">15.3</span> (2022-08-22) + +The ability to sort the Vulnerability Report by the `Tool` column (scan type) was disabled and put behind a feature flag in GitLab 14.10 due to a refactor +of the underlying data model. The feature flag has remained off by default as further refactoring will be required to ensure sorting +by this value remains performant. Due to very low usage of the `Tool` column for sorting, the feature flag will instead be removed in +GitLab 15.3 to simplify the codebase and prevent any unwanted performance degradation. + +</div> + +<div class="deprecation removal-160 breaking-change"> + +### project.pipeline.securityReportFindings GraphQL query + +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +Previous work helped [align the vulnerabilities calls for pipeline security tabs](https://gitlab.com/gitlab-org/gitlab/-/issues/343469) to match the vulnerabilities calls for project-level and group-level vulnerability reports. This helped the frontend have a more consistent interface. The old `project.pipeline.securityReportFindings` query was formatted differently than other vulnerability data calls. Now that it has been replaced with the new `project.pipeline.vulnerabilities` field, the old `project.pipeline.securityReportFindings` is being deprecated and will be removed in GitLab 16.0. + +</div> +</div> + +<div class="announcement-milestone"> + +## Announced in 15.0 <div class="deprecation removal-160 breaking-change"> ### CiCdSettingsUpdate mutation renamed to ProjectCiCdSettingsUpdate +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `CiCdSettingsUpdate` mutation was renamed to `ProjectCiCdSettingsUpdate` in GitLab 15.0. The `CiCdSettingsUpdate` mutation will be removed in GitLab 16.0. Any user scripts that use the `CiCdSettingsUpdate` mutation must be updated to use `ProjectCiCdSettingsUpdate` instead. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### GraphQL API legacyMode argument for Runner status +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `legacyMode` argument to the `status` field in `RunnerType` will be rendered non-functional in the 16.0 release as part of the deprecations details in the [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). @@ -84,18 +171,17 @@ In GitLab 16.0 and later, the `status` field will act as if `legacyMode` is null be present during the 16.x cycle to avoid breaking the API signature, and will be removed altogether in the 17.0 release. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### PostgreSQL 12 deprecated +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Support for PostgreSQL 12 is scheduled for removal in GitLab 16.0. In GitLab 16.0, PostgreSQL 13 becomes the minimum required PostgreSQL version. @@ -105,50 +191,49 @@ PostgreSQL 13 will also be supported for instances that want to upgrade prior to Upgrading to PostgreSQL 13 is not yet supported for GitLab instances with Geo enabled. Geo support for PostgreSQL 13 will be announced in a minor release version of GitLab 15, after the process is fully supported and validated. For more information, read the Geo related verifications on the [support epic for PostgreSQL 13](https://gitlab.com/groups/gitlab-org/-/epics/3832). -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-152"> ### Vulnerability Report sort by State +Planned removal: GitLab <span class="removal-milestone">15.2</span> (2022-07-22) + The ability to sort the Vulnerability Report by the `State` column was disabled and put behind a feature flag in GitLab 14.10 due to a refactor of the underlying data model. The feature flag has remained off by default as further refactoring will be required to ensure sorting by this value remains performant. Due to very low usage of the `State` column for sorting, the feature flag will instead be removed in GitLab 15.2 to simplify the codebase and prevent any unwanted performance degradation. -**Planned removal milestone: <span class="removal-milestone">15.2</span> (2022-07-22)** </div> </div> <div class="announcement-milestone"> -## 14.10 +## Announced in 14.10 <div class="deprecation removal-150 breaking-change"> ### Dependency Scanning default Java version changed to 17 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 15.0, for Dependency Scanning, the default version of Java that the scanner expects will be updated from 11 to 17. Java 17 is [the most up-to-date Long Term Support (LTS) version](https://en.wikipedia.org/wiki/Java_version_history). Dependency scanning continues to support the same [range of versions (8, 11, 13, 14, 15, 16, 17)](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#supported-languages-and-package-managers), only the default version is changing. If your project uses the previous default of Java 11, be sure to [set the `DS_Java_Version` variable to match](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#configuring-specific-analyzers-used-by-dependency-scanning). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2021-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### Manual iteration management +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Manual iteration management is deprecated and only automatic iteration cadences will be supported in the future. @@ -170,55 +255,52 @@ arguments will be removed: For more information about iteration cadences, you can refer to [the documentation of the feature](https://docs.gitlab.com/ee/user/group/iterations/#iteration-cadences). -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-04-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Outdated indices of Advanced Search migrations +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As Advanced Search migrations usually require support multiple code paths for a long period of time, it’s important to clean those up when we safely can. We use GitLab major version upgrades as a safe time to remove backward compatibility for indices that have not been fully migrated. See the [upgrade documentation](https://docs.gitlab.com/ee/update/index.html#upgrading-to-a-new-major-version) for details. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2021-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### Toggle notes confidentiality on APIs +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Toggling notes confidentiality with REST and GraphQL APIs is being deprecated. Updating notes confidential attribute is no longer supported by any means. We are changing this to simplify the experience and prevent private information from being unintentionally exposed. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> </div> <div class="announcement-milestone"> -## 14.9 +## Announced in 14.9 <div class="deprecation removal-150 breaking-change"> ### Background upload for object storage +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. -To reduce the overall complexity and maintenance burden of GitLab's [object storage feature](https://docs.gitlab.com/ee/administration/object_storage.html), support for using `background_upload` to upload files is deprecated and will be fully removed in GitLab 15.0. +To reduce the overall complexity and maintenance burden of GitLab's [object storage feature](https://docs.gitlab.com/ee/administration/object_storage.html), support for using `background_upload` to upload files is deprecated and will be fully removed in GitLab 15.0. Review the [15.0 specific changes](https://docs.gitlab.com/omnibus/update/gitlab_15_changes.html) for the [removed background uploads settings for object storage](https://docs.gitlab.com/omnibus/update/gitlab_15_changes.html#removed-background-uploads-settings-for-object-storage). This impacts a small subset of object storage providers: @@ -227,51 +309,51 @@ This impacts a small subset of object storage providers: GitLab will publish additional guidance to assist affected customers in migrating. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-151"> ### Deprecate support for Debian 9 +Planned removal: GitLab <span class="removal-milestone">15.1</span> (2022-06-22) + Long term service and support (LTSS) for [Debian 9 Stretch ends in July 2022](https://wiki.debian.org/LTS). Therefore, we will no longer support the Debian 9 distribution for the GitLab package. Users can upgrade to Debian 10 or Debian 11. -**Planned removal milestone: <span class="removal-milestone">15.1</span> (2022-06-22)** </div> <div class="deprecation removal-150"> ### GitLab Pages running as daemon +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + In 15.0, support for daemon mode for GitLab Pages will be removed. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### GitLab self-monitoring project +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab self-monitoring gives administrators of self-hosted GitLab instances the tools to monitor the health of their instances. This feature is deprecated in GitLab 14.9, and is scheduled for removal in 16.0. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### GraphQL permissions change for Package settings +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Package stage offers a Package Registry, Container Registry, and Dependency Proxy to help you manage all of your dependencies using GitLab. Each of these product categories has a variety of settings that can be adjusted using the API. @@ -282,95 +364,93 @@ The permissions model for GraphQL is being updated. After 15.0, users with the G - [Dependency Proxy time-to-live policy](https://docs.gitlab.com/ee/api/graphql/reference/#dependencyproxyimagettlgrouppolicy) - [Enabling the Dependency Proxy for your group](https://docs.gitlab.com/ee/api/graphql/reference/#dependencyproxysetting) -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Move `custom_hooks_dir` setting from GitLab Shell to Gitaly +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + The [`custom_hooks_dir`](https://docs.gitlab.com/ee/administration/server_hooks.html#create-a-global-server-hook-for-all-repositories) setting is now configured in Gitaly, and will be removed from GitLab Shell in GitLab 15.0. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-1410 breaking-change"> ### Permissions change for downloading Composer dependencies +Planned removal: GitLab <span class="removal-milestone">14.10</span> (2022-04-22) + WARNING: -This feature will be changed or removed in 14.10 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Composer repository can be used to push, search, fetch metadata about, and download PHP dependencies. All these actions require authentication, except for downloading dependencies. Downloading Composer dependencies without authentication is deprecated in GitLab 14.9, and will be removed in GitLab 15.0. Starting with GitLab 15.0, you must authenticate to download Composer dependencies. -**Planned removal milestone: <span class="removal-milestone">14.10</span> (2022-04-22)** </div> <div class="deprecation removal-150 breaking-change"> ### htpasswd Authentication for the Container Registry +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The Container Registry supports [authentication](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md#auth) with `htpasswd`. It relies on an [Apache `htpasswd` file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html), with passwords hashed using `bcrypt`. Since it isn't used in the context of GitLab (the product), `htpasswd` authentication will be deprecated in GitLab 14.9 and removed in GitLab 15.0. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### user_email_lookup_limit API field +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `user_email_lookup_limit` [API field](https://docs.gitlab.com/ee/api/settings.html) is deprecated and will be removed in GitLab 15.0. Until GitLab 15.0, `user_email_lookup_limit` is aliased to `search_rate_limit` and existing workflows will continue to work. Any API calls attempting to change the rate limits for `user_email_lookup_limit` should use `search_rate_limit` instead. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> </div> <div class="announcement-milestone"> -## 14.8 +## Announced in 14.8 <div class="deprecation removal-149"> ### Configurable Gitaly `per_repository` election strategy +Planned removal: GitLab <span class="removal-milestone">14.9</span> (2022-03-22) + Configuring the `per_repository` Gitaly election strategy is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352612). `per_repository` has been the only option since GitLab 14.0. This change is part of regular maintenance to keep our codebase clean. -**Planned removal milestone: <span class="removal-milestone">14.9</span> (2022-03-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Container Network and Host Security +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. All functionality related to GitLab's Container Network Security and Container Host Security categories is deprecated in GitLab 14.8 and scheduled for removal in GitLab 15.0. Users who need a replacement for this functionality are encouraged to evaluate the following open source projects as potential solutions that can be installed and managed outside of GitLab: [AppArmor](https://gitlab.com/apparmor/apparmor), [Cilium](https://github.com/cilium/cilium), [Falco](https://github.com/falcosecurity/falco), [FluentD](https://github.com/fluent/fluentd), [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/). To integrate these technologies into GitLab, add the desired Helm charts into your copy of the [Cluster Management Project Template](https://docs.gitlab.com/ee/user/clusters/management_project_template.html). Deploy these Helm charts in production by calling commands through GitLab [CI/CD](https://docs.gitlab.com/ee/user/clusters/agent/ci_cd_workflow.html). @@ -383,18 +463,17 @@ As part of this change, the following specific capabilities within GitLab are no For additional context, or to provide feedback regarding this change, please reference our open [deprecation issue](https://gitlab.com/groups/gitlab-org/-/epics/7476). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Dependency Scanning Python 3.9 and 3.6 image deprecation +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. For those using Dependency Scanning for Python projects, we are deprecating the default `gemnasium-python:2` image which uses Python 3.6 as well as the custom `gemnasium-python:2-python-3.9` image which uses Python 3.9. The new default image as of GitLab 15.0 will be for Python 3.9 as it is a [supported version](https://endoflife.date/python) and 3.6 [is no longer supported](https://endoflife.date/python). @@ -416,22 +495,24 @@ gemnasium-python-dependency_scanning: name: registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python:2-python-3.9 ``` -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2021-05-22)** </div> <div class="deprecation removal-150"> ### Deprecate Geo Admin UI Routes +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + In GitLab 13.0, we introduced new project and design replication details routes in the Geo Admin UI. These routes are `/admin/geo/replication/projects` and `/admin/geo/replication/designs`. We kept the legacy routes and redirected them to the new routes. In GitLab 15.0, we will remove support for the legacy routes `/admin/geo/projects` and `/admin/geo/designs`. Please update any bookmarks or scripts that may use the legacy routes. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Deprecate custom Geo:db:* Rake tasks +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + In GitLab 14.8, we are [replacing the `geo:db:*` Rake tasks with built-in tasks](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77269/diffs) that are now possible after [switching the Geo tracking database to use Rails' 6 support of multiple databases](https://gitlab.com/groups/gitlab-org/-/epics/6458). The following `geo:db:*` tasks will be replaced with their corresponding `db:*:geo` tasks: @@ -453,33 +534,31 @@ The following `geo:db:*` tasks will be replaced with their corresponding `db:*:g - `geo:db:test:load` -> `db:test:load:geo` - `geo:db:test:purge` -> `db:test:purge:geo` -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Deprecate feature flag PUSH_RULES_SUPERSEDE_CODE_OWNERS +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The feature flag `PUSH_RULES_SUPERSEDE_CODE_OWNERS` is being removed in GitLab 15.0. Upon its removal, push rules will supersede CODEOWNERS. The CODEOWNERS feature will no longer be available for access control. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Deprecate legacy Gitaly configuration methods +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Using environment variables `GIT_CONFIG_SYSTEM` and `GIT_CONFIG_GLOBAL` to configure Gitaly is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/352609). These variables are being replaced with standard [`config.toml` Gitaly configuration](https://docs.gitlab.com/ee/administration/gitaly/reference.html). @@ -487,18 +566,17 @@ These variables are being replaced with standard [`config.toml` Gitaly configura GitLab instances that use `GIT_CONFIG_SYSTEM` and `GIT_CONFIG_GLOBAL` to configure Gitaly should switch to configuring using `config.toml`. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Elasticsearch 6.8 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Elasticsearch 6.8 is deprecated in GitLab 14.8 and scheduled for removal in GitLab 15.0. Customers using Elasticsearch 6.8 need to upgrade their Elasticsearch version to 7.x prior to upgrading to GitLab 15.0. @@ -506,18 +584,17 @@ We recommend using the latest version of Elasticsearch 7 to benefit from all Ela Elasticsearch 6.8 is also incompatible with Amazon OpenSearch, which we [plan to support in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/327560). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### External status check API breaking changes +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The [external status check API](https://docs.gitlab.com/ee/api/status_checks.html) was originally implemented to support pass-by-default requests to mark a status check as passing. Pass-by-default requests are now deprecated. @@ -535,18 +612,17 @@ and set to `passed`. Requests that: To align with this change, API calls to list external status checks will also return the value of `passed` rather than `approved` for status checks that have passed. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### GraphQL ID and GlobalID compatibility +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-04-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We are removing a non-standard extension to our GraphQL processor, which we added for backwards compatibility. This extension modifies the validation of GraphQL queries, allowing the use of the `ID` type for arguments where it would normally be rejected. Some arguments originally had the type `ID`. These were changed to specific @@ -600,18 +676,17 @@ You should convert any queries in the first form (using `ID` as a named type in to one of the other two forms (using the correct appropriate type in the signature, or using an inline argument expression). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-04-22)** </div> <div class="deprecation removal-150 breaking-change"> ### OAuth tokens without expiration +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. By default, all new applications expire access tokens after 2 hours. In GitLab 14.2 and earlier, OAuth access tokens had no expiration. In GitLab 15.0, an expiry will be automatically generated for any existing token that does not @@ -623,52 +698,49 @@ tokens before GitLab 15.0 is released: 1. Edit the application. 1. Select **Expire access tokens** to enable them. Tokens must be revoked or they don’t expire. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Optional enforcement of PAT expiration +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The feature to disable enforcement of PAT expiration is unusual from a security perspective. We have become concerned that this unusual feature could create unexpected behavior for users. Unexpected behavior in a security feature is inherently dangerous, so we have decided to remove this feature. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Optional enforcement of SSH expiration +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The feature to disable enforcement of SSH expiration is unusual from a security perspective. We have become concerned that this unusual feature could create unexpected behavior for users. Unexpected behavior in a security feature is inherently dangerous, so we have decided to remove this feature. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Out-of-the-box SAST support for Java 8 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The [GitLab SAST SpotBugs analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs) scans [Java, Scala, Groovy, and Kotlin code](https://docs.gitlab.com/ee/user/application_security/sast/#supported-languages-and-frameworks) for security vulnerabilities. For technical reasons, the analyzer must first compile the code before scanning. @@ -683,33 +755,31 @@ In GitLab 15.0, we will: If you rely on Java 8 being present in the analyzer environment, you must take action as detailed in the [deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/352549#breaking-change). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Querying Usage Trends via the `instanceStatisticsMeasurements` GraphQL node +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `instanceStatisticsMeasurements` GraphQL node has been renamed to `usageTrendsMeasurements` in 13.10 and the old field name has been marked as deprecated. To fix the existing GraphQL queries, replace `instanceStatisticsMeasurements` with `usageTrendsMeasurements`. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### REST API Runner will not accept `status` filter values of `active` or `paused` +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Runner REST endpoints will stop accepting `paused` or `active` as a status value in GitLab 16.0. @@ -719,33 +789,31 @@ Status values `paused` or `active` will no longer be accepted and will be replac When checking for paused runners, API users are advised to specify `paused=true` as the query parameter. When checking for active runners, specify `paused=false`. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-04-22)** </div> <div class="deprecation removal-160 breaking-change"> ### REST API endpoint to list group runners no longer accepts `project_type` value for `type` argument +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `GET /groups/:id/runners?type=project_type` endpoint will be removed in GitLab 16.0. The endpoint always returned an empty collection. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-04-22)** </div> <div class="deprecation removal-160 breaking-change"> ### REST and GraphQL API Runner usage of `active` replaced by `paused` +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Occurrences of the `active` identifier in the GitLab Runner REST and GraphQL API endpoints will be renamed to `paused` in GitLab 16.0, namely: @@ -767,18 +835,17 @@ The 16.0 release of the GitLab Runner will start using the `paused` property whe will only be compatible with GitLab 16.0 and later. Until 16.0, GitLab will accept the deprecated `active` flag from existing runners. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-04-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Request profiling +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. [Request profiling](https://docs.gitlab.com/ee/administration/monitoring/performance/request_profiling.html) is deprecated in GitLab 14.8 and scheduled for removal in GitLab 15.0. @@ -788,18 +855,17 @@ It also depends on a few third-party gems that are not actively maintained anymo For more information, check the [summary section of the deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352488#deprecation-summary). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Required pipeline configurations in Premium tier +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The [required pipeline configuration](https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#required-pipeline-configuration) feature is deprecated in GitLab 14.8 for Premium customers and is scheduled for removal in GitLab 15.0. This feature is not deprecated for GitLab Ultimate customers. @@ -808,35 +874,33 @@ This change to move the feature to GitLab's Ultimate tier is intended to help ou This change will also help GitLab remain consistent in its tiering strategy with the other related Ultimate-tier features of: [Security policies](https://docs.gitlab.com/ee/user/application_security/policies/) and [compliance framework pipelines](https://docs.gitlab.com/ee/user/project/settings/index.html#compliance-pipeline-configuration). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Retire-JS Dependency Scanning tool +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As of 14.8 the retire.js job is being deprecated from Dependency Scanning. It will continue to be included in our CI/CD template while deprecated. We are removing retire.js from Dependency Scanning on May 22, 2022 in GitLab 15.0. JavaScript scanning functionality will not be affected as it is still being covered by Gemnasium. If you have explicitly excluded retire.js using DS_EXCLUDED_ANALYZERS you will need to clean up (remove the reference) in 15.0. If you have customized your pipeline's Dependency Scanning configuration related to the `retire-js-dependency_scanning` job you will want to switch to gemnasium-dependency_scanning before the removal in 15.0, to prevent your pipeline from failing. If you have not used the DS_EXCLUDED_ANALYZERS to reference retire.js, or customized your template specifically for retire.js, you will not need to take action. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-152 breaking-change"> ### SAST analyzer consolidation and CI/CD template changes +Planned removal: GitLab <span class="removal-milestone">15.2</span> (2022-07-22) + WARNING: -This feature will be changed or removed in 15.2 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab SAST uses various [analyzers](https://docs.gitlab.com/ee/user/application_security/sast/analyzers/) to scan code for vulnerabilities. @@ -862,18 +926,17 @@ This change will be reflected in the automatic language detection portion of the If you applied customizations to any of the affected analyzers or if you currently disable the Semgrep analyzer in your pipelines, you must take action as detailed in the [deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/352554#breaking-change). -**Planned removal milestone: <span class="removal-milestone">15.2</span> (2022-07-22)** </div> <div class="deprecation removal-150 breaking-change"> ### SAST support for .NET 2.1 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab SAST Security Code Scan analyzer scans .NET code for security vulnerabilities. For technical reasons, the analyzer must first build the code to scan it. @@ -895,13 +958,14 @@ Version 3 was [announced in GitLab 14.6](https://about.gitlab.com/releases/2021/ If you rely on .NET 2.1 support being present in the analyzer image by default, you must take action as detailed in the [deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/352553#breaking-change). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Secret Detection configuration variables deprecated +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + To make it simpler and more reliable to [customize GitLab Secret Detection](https://docs.gitlab.com/ee/user/application_security/secret_detection/#customizing-settings), we're deprecating some of the variables that you could previously set in your CI/CD configuration. The following variables currently allow you to customize the options for historical scanning, but interact poorly with the [GitLab-managed CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) and are now deprecated: @@ -919,18 +983,17 @@ You'll still be able to configure historical scanning of your commit history by For further details, see [the deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/352565). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Secure and Protect analyzer images published in new location +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab uses various [analyzers](https://docs.gitlab.com/ee/user/application_security/terminology/#analyzer) to [scan for security vulnerabilities](https://docs.gitlab.com/ee/user/application_security/). Each analyzer is distributed as a container image. @@ -948,25 +1011,24 @@ Otherwise, you won't receive further updates. See the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352564) for more details. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Secure and Protect analyzer major version update +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The Secure and Protect stages will be bumping the major versions of their analyzers in tandem with the GitLab 15.0 release. This major bump will enable a clear delineation for analyzers, between: - Those released prior to May 22, 2022, which generate reports that _are not_ subject to stringent schema validation. - Those released after May 22, 2022, which generate reports that _are_ subject to stringent schema validation. -If you are not using the default inclusion templates, or have pinned your analyzer version(s) you will need to update your CI/CD job definition to either remove the pinned version or to update the latest major version. +If you are not using the default inclusion templates, or have pinned your analyzer versions you will need to update your CI/CD job definition to either remove the pinned version or to update the latest major version. Users of GitLab 12.0-14.10 will continue to experience analyzer updates as normal until the release of GitLab 15.0, following which all newly fixed bugs and newly released features in the new major versions of the analyzers will not be available in the deprecated versions because we do not backport bugs and new features as per our [maintenance policy](https://docs.gitlab.com/ee/policy/maintenance.html). As required security patches will be backported within the latest 3 minor releases. Specifically, the following are being deprecated and will no longer be updated after 15.0 GitLab release: @@ -994,18 +1056,17 @@ Specifically, the following are being deprecated and will no longer be updated a - `sobelow`: version 2 - `spotbugs`: version 2 -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Support for gRPC-aware proxy deployed between Gitaly and rest of GitLab +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Although not recommended or documented, it was possible to deploy a gRPC-aware proxy between Gitaly and the rest of GitLab. For example, NGINX and Envoy. The ability to deploy a gRPC-aware proxy is @@ -1019,18 +1080,17 @@ By sending some of our internal RPC traffic through a custom protocol (instead o increase throughput and reduce Go garbage collection latency. For more information, see the [relevant epic](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/463). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Test coverage project CI/CD setting +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. To simplify setting a test coverage pattern, in GitLab 15.0 the [project setting for test coverage parsing](https://docs.gitlab.com/ee/ci/pipelines/settings.html#add-test-coverage-results-using-project-settings-removed) @@ -1039,18 +1099,17 @@ is being removed. Instead, using the project’s `.gitlab-ci.yml`, provide a regular expression with the `coverage` keyword to set testing coverage results in merge requests. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Vulnerability Check +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The vulnerability check feature is deprecated in GitLab 14.8 and scheduled for removal in GitLab 15.0. We encourage you to migrate to the new security approvals feature instead. You can do so by navigating to **Security & Compliance > Policies** and creating a new Scan Result Policy. @@ -1061,18 +1120,17 @@ The new security approvals feature is similar to vulnerability check. For exampl - A two-step approval process can be enforced for any desired changes to security approval rules. - A single set of security policies can be applied to multiple development projects to allow for ease in maintaining a single, centralized ruleset. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### `CI_BUILD_*` predefined variables +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The predefined CI/CD variables that start with `CI_BUILD_*` were deprecated in GitLab 9.0, and will be removed in GitLab 16.0. If you still use these variables, be sure to change to the replacement [predefined variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) which are functionally identical: @@ -1091,66 +1149,50 @@ The predefined CI/CD variables that start with `CI_BUILD_*` were deprecated in G | `CI_BUILD_TOKEN` | `CI_JOB_TOKEN` | | `CI_BUILD_TRIGGERED` | `CI_PIPELINE_TRIGGERED` | -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-04-22)** -</div> - -<div class="deprecation removal-150"> - -### `fixup!` commit messages setting draft status of associated Merge Request - -The use of `fixup!` as a commit message to trigger draft status -of the associated Merge Request is generally unused, and can cause -confusion with other uses of the term. "Draft" is the preferred -and supported trigger for triggering draft status from commit -messages, as part of our streamlining of the feature. -Support for `fixup!` is now considered deprecated, and will be -removed in GitLab 15.0. - -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-06-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `projectFingerprint` in `PipelineSecurityReportFinding` GraphQL +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `projectFingerprint` field in the [PipelineSecurityReportFinding](https://docs.gitlab.com/ee/api/graphql/reference/index.html#pipelinesecurityreportfinding) GraphQL object is being deprecated. This field contains a "fingerprint" of security findings used to determine uniqueness. The method for calculating fingerprints has changed, resulting in different values. Going forward, the new values will be exposed in the UUID field. Data previously available in the projectFingerprint field will eventually be removed entirely. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `started` iterations API field +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `started` field in the [iterations API](https://docs.gitlab.com/ee/api/iterations.html#list-project-iterations) is being deprecated and will be removed in GitLab 15.0. This field is being replaced with the `current` field (already available) which aligns with the naming for other time-based entities, such as milestones. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> </div> <div class="announcement-milestone"> -## 14.7 +## Announced in 14.7 <div class="deprecation removal-150"> ### Container scanning schemas below 14.0.0 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [Container scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported in GitLab 15.0. @@ -1162,13 +1204,14 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Coverage guided fuzzing schemas below 14.0.0 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [Coverage guided fuzzing report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) below version 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported in GitLab 15.0. @@ -1183,13 +1226,14 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### DAST schemas below 14.0.0 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [DAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported as of GitLab 15.0. @@ -1204,13 +1248,14 @@ To help with the transition, from GitLab 14.10, non-compliant reports will cause [warning to be displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Dependency scanning schemas below 14.0.0 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [Dependency scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported as of GitLab 15.0. @@ -1225,13 +1270,14 @@ To help with the transition, from GitLab 14.10, non-compliant reports will cause [warning to be displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Enforced validation of security report schemas +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [Security report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported in GitLab 15.0. @@ -1246,68 +1292,69 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Godep support in License Compliance +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + The Godep dependency manager for Golang was deprecated in 2020 by Go and has been replaced with Go modules. To reduce our maintenance cost we are deprecating License Compliance for Godep projects as of 14.7 and will remove it in GitLab 15.0 -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Logging in GitLab +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The logging features in GitLab allow users to install the ELK stack (Elasticsearch, Logstash, and Kibana) to aggregate and manage application logs. Users can search for relevant logs in GitLab. However, since deprecating certificate-based integration with Kubernetes clusters and GitLab Managed Apps, we don't have a recommended solution for logging within GitLab. For more information, you can follow the issue for [integrating Opstrace with GitLab](https://gitlab.com/groups/gitlab-org/-/epics/6976). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### Monitor performance metrics through Prometheus +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. By displaying data stored in a Prometheus instance, GitLab allows users to view performance metrics. GitLab also displays visualizations of these metrics in dashboards. The user can connect to a previously-configured external Prometheus instance, or set up Prometheus as a GitLab Managed App. However, since certificate-based integration with Kubernetes clusters is deprecated in GitLab, the metrics functionality in GitLab that relies on Prometheus is also deprecated. This includes the metrics visualizations in dashboards. GitLab is working to develop a single user experience based on [Opstrace](https://about.gitlab.com/press/releases/2021-12-14-gitlab-acquires-opstrace-to-expand-its-devops-platform-with-open-source-observability-solution.html). An [issue exists](https://gitlab.com/groups/gitlab-org/-/epics/6976) for you to follow work on the Opstrace integration. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-150"> ### Pseudonymizer +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + The Pseudonymizer feature is generally unused, can cause production issues with large databases, and can interfere with object storage development. It is now considered deprecated, and will be removed in GitLab 15.0. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### SAST schemas below 14.0.0 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [SAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported as of GitLab 15.0. @@ -1322,13 +1369,14 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Secret detection schemas below 14.0.0 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + [Secret detection report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation against the schema version declared in the report will also no longer be supported as of GitLab 15.0. @@ -1343,18 +1391,17 @@ To help with the transition, from GitLab 14.10, non-compliant reports will displ [warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) in the Vulnerability Report. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Sidekiq metrics and health checks configuration +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Exporting Sidekiq metrics and health checks using a single process and port is deprecated. Support will be removed in 15.0. @@ -1376,162 +1423,156 @@ and only run one server (not changing the current behaviour). Only if they are both set and a different port is provided, a separate metrics server will spin up to serve the Sidekiq metrics, similar to the way Sidekiq will behave in 15.0. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### Static Site Editor +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + The Static Site Editor will no longer be available starting in GitLab 15.0. Improvements to the Markdown editing experience across GitLab will deliver smiliar benefit but with a wider reach. Incoming requests to the Static Site Editor will be redirected to the [Web IDE](https://docs.gitlab.com/ee/user/project/web_ide/index.html). Current users of the Static Site Editor can view the [documentation](https://docs.gitlab.com/ee/user/project/static_site_editor/) for more information, including how to remove the configuration files from existing projects. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Tracing in GitLab +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distributed tracing system. GitLab users can navigate to their Jaeger instance to gain insight into the performance of a deployed application, tracking each function or microservice that handles a given request. Tracing in GitLab is deprecated in GitLab 14.7, and scheduled for removal in 15.0. To track work on a possible replacement, see the issue for [Opstrace integration with GitLab](https://gitlab.com/groups/gitlab-org/-/epics/6976). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150"> ### `artifacts:report:cobertura` keyword +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + Currently, test coverage visualizations in GitLab only support Cobertura reports. Starting 15.0, the `artifacts:report:cobertura` keyword will be replaced by [`artifacts:reports:coverage_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/344533). Cobertura will be the only supported report file in 15.0, but this is the first step towards GitLab supporting other report types. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### merged_by API field +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `merged_by` field in the [merge request API](https://docs.gitlab.com/ee/api/merge_requests.html#list-merge-requests) is being deprecated and will be removed in GitLab 15.0. This field is being replaced with the `merge_user` field (already present in GraphQL) which more correctly identifies who merged a merge request when performing actions (merge when pipeline succeeds, add to merge train) other than a simple merge. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> </div> <div class="announcement-milestone"> -## 14.6 +## Announced in 14.6 <div class="deprecation removal-150 breaking-change"> ### CI/CD job name length limit +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 15.0 we are going to limit the number of characters in CI/CD job names to 255. Any pipeline with job names that exceed the 255 character limit will stop working after the 15.0 release. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Legacy approval status names from License Compliance API +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We deprecated legacy names for approval status of license policy (blacklisted, approved) in the `managed_licenses` API but they are still used in our API queries and responses. They will be removed in 15.0. If you are using our License Compliance API you should stop using the `approved` and `blacklisted` query parameters, they are now `allowed` and `denied`. In 15.0 the responses will also stop using `approved` and `blacklisted` so you need to adjust any of your custom tools to use the old and new values so they do not break with the 15.0 release. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `type` and `types` keyword in CI/CD configuration +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines that use these keywords will stop working, so you must switch to `stage` and `stages`, which have the same behavior. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### apiFuzzingCiConfigurationCreate GraphQL mutation +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The API Fuzzing configuration snippet is now being generated client-side and does not require an API request anymore. We are therefore deprecating the `apiFuzzingCiConfigurationCreate` mutation which isn't being used in GitLab anymore. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### bundler-audit Dependency Scanning tool +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As of 14.6 bundler-audit is being deprecated from Dependency Scanning. It will continue to be in our CI/CD template while deprecated. We are removing bundler-audit from Dependency Scanning on May 22, 2022 in 15.0. After this removal Ruby scanning functionality will not be affected as it is still being covered by Gemnasium. If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you will need to clean up (remove the reference) in 15.0. If you have customized your pipeline's Dependency Scanning configuration, for example to edit the `bundler-audit-dependency_scanning` job, you will want to switch to gemnasium-dependency_scanning before removal in 15.0, to prevent your pipeline from failing. If you have not used the DS_EXCLUDED_ANALYZERS to reference bundler-audit, or customized your template specifically for bundler-audit, you will not need to take action. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> </div> <div class="announcement-milestone"> -## 14.5 +## Announced in 14.5 <div class="deprecation removal-150 breaking-change"> ### Changing an instance (shared) runner to a project (specific) runner +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 15.0, you can no longer change an instance (shared) runner to a project (specific) runner. @@ -1539,69 +1580,49 @@ Users often accidentally change instance runners to project runners, and they're Administrators who need to add runners for multiple projects can register a runner for one project, then go to the Admin view and choose additional projects. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Known host required for GitLab Runner SSH executor +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3074), we added a configuration setting in the GitLab Runner `config.toml` file. This setting, [`[runners.ssh.disable_strict_host_key_checking]`](https://docs.gitlab.com/runner/executors/ssh.html#security), controls whether or not to use strict host key checking with the SSH executor. In GitLab 15.0 and later, the default value for this configuration option will change from `true` to `false`. This means that strict host key checking will be enforced when using the GitLab Runner SSH executor. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** -</div> - -<div class="deprecation removal-150 breaking-change"> - -### Must explicitly assign `AuthenticationType` for `[runners.cache.s3]` - -WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -In GitLab 15.0 and later, to access the AWS S3 cache, you must specify the `AuthenticationType` for [`[runners.cache.s3]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section). The `AuthenticationType` must be `IAM` or `credentials`. - -Prior to 14.5, if you did not define the `AuthenticationType`, GitLab Runner chose a type for you. - -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### Package pipelines in API payload is paginated +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. A request to the API for `/api/v4/projects/:id/packages` returns a paginated result of packages. Each package lists all of its pipelines in this response. This is a performance concern, as it's possible for a package to have hundreds or thousands of associated pipelines. In milestone 16.0, we will remove the `pipelines` attribute from the API response. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-160 breaking-change"> ### REST and GraphQL API Runner status will not return `paused` +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-04-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Runner REST and GraphQL API endpoints will not return `paused` or `active` as a status in GitLab 16.0. @@ -1611,18 +1632,17 @@ A runner's status will only relate to runner contact status, such as: When checking if a runner is `paused`, API users are advised to check the boolean attribute `paused` to be `true` instead. When checking if a runner is `active`, check if `paused` is `false`. -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-04-22)** </div> <div class="deprecation removal-156 breaking-change"> ### SaaS certificate-based integration with Kubernetes +Planned removal: GitLab <span class="removal-milestone">15.6</span> (2022-11-22) + WARNING: -This feature will be changed or removed in 15.6 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The certificate-based integration with Kubernetes will be [deprecated and removed](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/). As a GitLab SaaS customer, on new namespaces, you will no longer be able to integrate GitLab and your cluster using the certificate-based approach as of GitLab 15.0. The integration for current users will be enabled per namespace. The integrations are expected to be switched off completely on GitLab SaaS around 2022 November 22. @@ -1633,22 +1653,21 @@ For updates and details about this deprecation, follow [this epic](https://gitla GitLab self-managed customers can still use the feature [with a feature flag](https://docs.gitlab.com/ee/update/deprecations.html#self-managed-certificate-based-integration-with-kubernetes). -**Planned removal milestone: <span class="removal-milestone">15.6</span> (2022-11-22)** </div> <div class="deprecation removal-160 breaking-change"> ### Self-managed certificate-based integration with Kubernetes +Planned removal: GitLab <span class="removal-milestone">16.0</span> (2023-05-22) + WARNING: -This feature will be changed or removed in 16.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The certificate-based integration with Kubernetes [will be deprecated and removed](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/). -As a self-managed customer, we are introducing a feature flag in GitLab 15.0 so you can keep your certificate-based integration enabled. However, the feature flag will be disabled by default, so this change is a **breaking change**. +As a self-managed customer, we are introducing the [feature flag](../administration/feature_flags.md#enable-or-disable-the-feature) `certificate_based_clusters` in GitLab 15.0 so you can keep your certificate-based integration enabled. However, the feature flag will be disabled by default, so this change is a **breaking change**. In GitLab 16.0 we will remove both the feature and its related code. Until the final removal in 16.0, features built on this integration will continue to work, if you enable the feature flag. Until the feature is removed, GitLab will continue to fix security and critical issues as they arise. @@ -1657,116 +1676,109 @@ For a more robust, secure, forthcoming, and reliable integration with Kubernetes For updates and details about this deprecation, follow [this epic](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). -**Planned removal milestone: <span class="removal-milestone">16.0</span> (2023-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Support for SLES 12 SP2 +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 SP2 [ended on March 31, 2021](https://www.suse.com/lifecycle/). The CA certificates on SP2 include the expired DST root certificate, and it's not getting new CA certificate package updates. We have implemented some [workarounds](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/merge_requests/191), but we will not be able to continue to keep the build running properly. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Update to the Container Registry group-level API +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In milestone 15.0, support for the `tags` and `tags_count` parameters will be removed from the Container Registry API that [gets registry repositories from a group](../api/container_registry.md#within-a-group). The `GET /groups/:id/registry/repositories` endpoint will remain, but won't return any info about tags. To get the info about tags, you can use the existing `GET /registry/repositories/:id` endpoint, which will continue to support the `tags` and `tag_count` options as it does today. The latter must be called once per image repository. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Value Stream Analytics filtering calculation change +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We are changing how the date filter works in Value Stream Analytics. Instead of filtering by the time that the issue or merge request was created, the date filter will filter by the end event time of the given stage. This will result in completely different figures after this change has rolled out. If you monitor Value Stream Analytics metrics and rely on the date filter, to avoid losing data, you must save the data prior to this change. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `Versions` on base `PackageType` +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As part of the work to create a [Package Registry GraphQL API](https://gitlab.com/groups/gitlab-org/-/epics/6318), the Package group deprecated the `Version` type for the basic `PackageType` type and moved it to [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#packagedetailstype). In milestone 15.0, we will completely remove `Version` from `PackageType`. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `defaultMergeCommitMessageWithDescription` GraphQL API field +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprecated and will be removed in GitLab 15.0. For projects with a commit message template set, it will ignore the template. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `dependency_proxy_for_private_groups` feature flag +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We added a feature flag because [GitLab-#11582](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) changed how public groups use the Dependency Proxy. Prior to this change, you could use the Dependency Proxy without authentication. The change requires authentication to use the Dependency Proxy. In milestone 15.0, we will remove the feature flag entirely. Moving forward, you must authenticate when using the Dependency Proxy. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `pipelines` field from the `version` field +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/#packagedetailstype) to get the pipelines for package versions: @@ -1775,64 +1787,62 @@ In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDeta To mitigate possible performance problems, we will remove the `versions` field's `pipelines` field in milestone 15.0. Although you will no longer be able to get all pipelines for all versions of a package, you can still get the pipelines of a single version through the remaining `pipelines` field for that version. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `promote-db` command from `gitlab-ctl` +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-db` which is used to promote database nodes in multi-node Geo secondary sites. `gitlab-ctl promote-db` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### `promote-to-primary-node` command from `gitlab-ctl` +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-to-primary-node` which was only usable for single-node Geo sites. `gitlab-ctl promote-to-primary-node` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-148"> ### openSUSE Leap 15.2 packages +Planned removal: GitLab <span class="removal-milestone">14.8</span> (2022-02-22) + Distribution support and security updates for openSUSE Leap 15.2 are [ending December 2021](https://en.opensuse.org/Lifetime#openSUSE_Leap). Starting in 14.5 we are providing packages for openSUSE Leap 15.3, and will stop providing packages for openSUSE Leap 15.2 in the 14.8 milestone. -**Planned removal milestone: <span class="removal-milestone">14.8</span> (2022-02-22)** </div> </div> <div class="announcement-milestone"> -## 14.3 +## Announced in 14.3 <div class="deprecation removal-150 breaking-change"> ### Audit events for repository push events +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Audit events for [repository events](https://docs.gitlab.com/ee/administration/audit_events.html#removed-events) are now deprecated and will be removed in GitLab 15.0. @@ -1840,35 +1850,33 @@ These events have always been disabled by default and had to be manually enabled feature flag. Enabling them can cause too many events to be generated which can dramatically slow down GitLab instances. For this reason, they are being removed. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### GitLab Serverless +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. [GitLab Serverless](https://docs.gitlab.com/ee/user/project/clusters/serverless/) is a feature set to support Knative-based serverless development with automatic deployments and monitoring. We decided to remove the GitLab Serverless features as they never really resonated with our users. Besides, given the continuous development of Kubernetes and Knative, our current implementations do not even work with recent versions. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### Legacy database configuration +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The syntax of [GitLabs database](https://docs.gitlab.com/omnibus/settings/database.html) configuration located in `database.yml` is changing and the legacy format is deprecated. The legacy format @@ -1876,18 +1884,17 @@ supported using a single PostgreSQL adapter, whereas the new format is changing This deprecation mainly impacts users compiling GitLab from source because Omnibus will handle this configuration automatically. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> <div class="deprecation removal-150 breaking-change"> ### OmniAuth Kerberos gem +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `omniauth-kerberos` gem will be removed in our next major release, GitLab 15.0. @@ -1895,43 +1902,46 @@ This gem has not been maintained and has very little usage. We therefore plan to Note that we are not deprecating the Kerberos SPNEGO integration, only the old password-based Kerberos integration. -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> </div> <div class="announcement-milestone"> -## 14.2 +## Announced in 14.2 <div class="deprecation removal-146"> ### Release CLI distributed as a generic package +Planned removal: GitLab <span class="removal-milestone">14.6</span> (2021-12-22) + The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6. -**Planned removal milestone: <span class="removal-milestone">14.6</span> (2021-12-22)** </div> <div class="deprecation removal-145"> ### Rename Task Runner pod to Toolbox +Planned removal: GitLab <span class="removal-milestone">14.5</span> (2021-11-22) + The Task Runner pod is used to execute periodic housekeeping tasks within the GitLab application and is often confused with the GitLab Runner. Thus, [Task Runner will be renamed to Toolbox](https://gitlab.com/groups/gitlab-org/charts/-/epics/25). This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab/toolbox`. Resulting pods will be named along the lines of `{{ .Release.Name }}-toolbox`, which will often be `gitlab-toolbox`. They will be locatable with the label `app=toolbox`. -**Planned removal milestone: <span class="removal-milestone">14.5</span> (2021-11-22)** </div> </div> <div class="announcement-milestone"> -## 14.0 +## Announced in 14.0 <div class="deprecation removal-156"> ### NFS for Git repository storage +Planned removal: GitLab <span class="removal-milestone">15.6</span> (2022-11-22) + With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS on November 22, 2022. This was originally planned for May 22, 2022, but in an effort to allow continued maturity of Gitaly Cluster, we have chosen to extend our deprecation of support date. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support.html#gitaly-and-nfs) for further information. Gitaly Cluster offers tremendous benefits for our customers such as: @@ -1942,21 +1952,19 @@ Gitaly Cluster offers tremendous benefits for our customers such as: We encourage customers currently using NFS for Git repositories to plan their migration by reviewing our documentation on [migrating to Gitaly Cluster](https://docs.gitlab.com/ee/administration/gitaly/index.html#migrate-to-gitaly-cluster). -**Planned removal milestone: <span class="removal-milestone">15.6</span> (2022-11-22)** </div> <div class="deprecation removal-150 breaking-change"> ### OAuth implicit grant +Planned removal: GitLab <span class="removal-milestone">15.0</span> (2022-05-22) + WARNING: -This feature will be changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The OAuth implicit grant authorization flow will be removed in our next major release, GitLab 15.0. Any applications that use OAuth implicit grant should switch to alternative [supported OAuth flows](https://docs.gitlab.com/ee/api/oauth2.html). -**Planned removal milestone: <span class="removal-milestone">15.0</span> (2022-05-22)** </div> </div> diff --git a/doc/update/index.md b/doc/update/index.md index 779b8ccbc6a..416adb621d0 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -94,11 +94,13 @@ that can process jobs in the `background_migration` queue. ### Background migrations +#### Pending migrations + **For Omnibus installations:** ```shell sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' -sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count' +sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count' ``` **For installations from source:** @@ -106,7 +108,39 @@ sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigrati ```shell cd /home/git/gitlab sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' -sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending.count' +sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count' +``` + +#### Failed migrations + +**For Omnibus installations:** + +For GitLab 14.0-14.9: + +```shell +sudo gitlab-rails runner -e production 'Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count' +``` + +For GitLab 14.10 and later: + +```shell +sudo gitlab-rails runner -e production 'Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count' +``` + +**For installations from source:** + +For GitLab 14.0-14.9: + +```shell +cd /home/git/gitlab +sudo -u git -H bundle exec rails runner -e production 'Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count' +``` + +For GitLab 14.10 and later: + +```shell +cd /home/git/gitlab +sudo -u git -H bundle exec rails runner -e production 'Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count' ``` ### Batched background migrations @@ -250,24 +284,36 @@ See [troubleshooting batched background migrations](../user/admin_area/monitorin ## Dealing with running CI/CD pipelines and jobs -If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates fail. When GitLab is back online, the trace updates should self-heal. However, depending on the error, the GitLab Runner either retries or eventually terminates job handling. +If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates fail. When GitLab is back online, the trace updates should self-heal. However, depending on the error, the GitLab Runner either retries, or eventually terminates, job handling. As for the artifacts, the GitLab Runner attempts to upload them three times, after which the job eventually fails. -To address the above two scenario's, it is advised to do the following prior to upgrading: +To address the above two scenarios, it is advised to do the following prior to upgrading: 1. Plan your maintenance. -1. Pause your runners. +1. Pause your runners or block new jobs from starting by adding following to your `/etc/gitlab/gitlab.rb`: + + ```ruby + nginx['custom_gitlab_server_config'] = "location /api/v4/jobs/request {\n deny all;\n return 503;\n}\n" + ``` + + And reconfigure GitLab with: + + ```shell + sudo gitlab-ctl reconfigure + ``` + 1. Wait until all jobs are finished. 1. Upgrade GitLab. 1. [Update GitLab Runner](https://docs.gitlab.com/runner/install/index.html) to the same version as your GitLab version. Both versions [should be the same](https://docs.gitlab.com/runner/#gitlab-runner-versions). +1. Unpause your runners and unblock new jobs from starting by reverting the previous `/etc/gitlab/gitlab.rb` change. ## Checking for pending Advanced Search migrations **(PREMIUM SELF)** -This section is only applicable if you have enabled the [Elasticsearch integration](../integration/elasticsearch.md) **(PREMIUM SELF)**. +This section is only applicable if you have enabled the [Elasticsearch integration](../integration/advanced_search/elasticsearch.md) **(PREMIUM SELF)**. -Major releases require all [Advanced Search migrations](../integration/elasticsearch.md#advanced-search-migrations) +Major releases require all [Advanced Search migrations](../integration/advanced_search/elasticsearch.md#advanced-search-migrations) to be finished from the most recent minor release in your current version before the major version upgrade. You can find pending migrations by running the following command: @@ -287,11 +333,11 @@ sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations ### What do I do if my Advanced Search migrations are stuck? -See [how to retry a halted migration](../integration/elasticsearch.md#retry-a-halted-migration). +See [how to retry a halted migration](../integration/advanced_search/elasticsearch.md#retry-a-halted-migration). ### What do I do for the error `Elasticsearch version not compatible` -Confirm that your version of Elasticsearch or OpenSearch is [compatible with your version of GitLab](../integration/elasticsearch.md#version-requirements). +Confirm that your version of Elasticsearch or OpenSearch is [compatible with your version of GitLab](../integration/advanced_search/elasticsearch.md#version-requirements). ## Upgrading without downtime @@ -314,7 +360,7 @@ A *major* upgrade requires the following steps: It's also important to ensure that any [background migrations have been fully completed](#checking-for-background-migrations-before-upgrading) before upgrading to a new major version. -If you have enabled the [Elasticsearch integration](../integration/elasticsearch.md) **(PREMIUM SELF)**, then +If you have enabled the [Elasticsearch integration](../integration/advanced_search/elasticsearch.md) **(PREMIUM SELF)**, then [ensure all Advanced Search migrations are completed](#checking-for-pending-advanced-search-migrations) in the last minor version within your current version before proceeding with the major version upgrade. @@ -333,7 +379,7 @@ Find where your version sits in the upgrade path below, and upgrade GitLab accordingly, while also consulting the [version-specific upgrade instructions](#version-specific-upgrading-instructions): -`8.11.Z` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> [`12.10.14`](#12100) -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [`13.12.15`](#13120) -> [`14.0.12`](#1400) -> [`14.9.0`](#1490) -> [latest `14.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) +`8.11.Z` -> `8.12.0` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> [`11.11.8`](#1200) -> `12.0.12` -> [`12.1.17`](#1210) -> [`12.10.14`](#12100) -> `13.0.14` -> [`13.1.11`](#1310) -> [`13.8.8`](#1388) -> [`13.12.15`](#13120) -> [`14.0.12`](#1400) -> [`14.3.6`](#1430) -> [`14.9.5`](#1490) -> [`14.10.Z`](#1410) -> [`15.0.Z`](#1500) -> [latest `15.Y.Z`](https://gitlab.com/gitlab-org/gitlab/-/releases) The following table, while not exhaustive, shows some examples of the supported upgrade paths. @@ -341,7 +387,9 @@ Additional steps between the mentioned versions are possible. We list the minima | Target version | Your version | Supported upgrade path | Note | | -------------- | ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `14.6.2` | `13.10.2` | `13.10.2` -> `13.12.15` -> `14.0.12` -> `14.6.2` | Two intermediate versions are required: `13.12` and `14.0`, then `14.6.2`. | +| `15.1.0` | `14.6.2` | `14.6.2` -> `14.9.5` -> `14.10.4` -> `15.0.2` -> `15.1.0` | Three intermediate versions are required: `14.9` and `14.10`, `15.0`, then `15.1.0`. | +| `15.0.0` | `14.6.2` | `14.6.2` -> `14.9.5` -> `14.10.4` -> `15.0.2` | Two intermediate versions are required: `14.9` and `14.10`, then `15.0.0`. | +| `14.6.2` | `13.10.2` | `13.10.2` -> `13.12.15` -> `14.0.12` -> `14.3.6` => `14.6.2` | Three intermediate versions are required: `13.12` and `14.0`, `14.3`, then `14.6.2`. | | `14.1.8` | `13.9.2` | `13.9.2` -> `13.12.15` -> `14.0.12` -> `14.1.8` | Two intermediate versions are required: `13.12` and `14.0`, then `14.1.8`. | | `13.12.15` | `12.9.2` | `12.9.2` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.8.8` -> `13.12.15` | Four intermediate versions are required: `12.10`, `13.0`, `13.1` and `13.8.8`, then `13.12.15`. | | `13.2.10` | `11.5.0` | `11.5.0` -> `11.11.8` -> `12.0.12` -> `12.1.17` -> `12.10.14` -> `13.0.14` -> `13.1.11` -> `13.2.10` | Six intermediate versions are required: `11.11`, `12.0`, `12.1`, `12.10`, `13.0` and `13.1`, then `13.2.10`. | @@ -383,7 +431,7 @@ possible. ## Version-specific upgrading instructions -Each month, major, minor or patch releases of GitLab are published along with a +Each month, major, minor, or patch releases of GitLab are published along with a [release post](https://about.gitlab.com/releases/categories/releases/). You should read the release posts for all versions you're passing over. At the end of major and minor release posts, there are three sections to look for specifically: @@ -396,7 +444,7 @@ These include: - Steps you need to perform as part of an upgrade. For example [8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/#upgrade-barometer) - required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or higher would require this. + required the Elasticsearch index to be recreated. Any older version of GitLab upgrading to 8.12 or later would require this. - Changes to the versions of software we support such as [ceasing support for IE11 in GitLab 13](https://about.gitlab.com/releases/2020/03/22/gitlab-12-9-released/#ending-support-for-internet-explorer-11). @@ -410,43 +458,68 @@ NOTE: Specific information that follow related to Ruby and Git versions do not apply to [Omnibus installations](https://docs.gitlab.com/omnibus/) and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with appropriate Ruby and Git versions and are not using system binaries for Ruby and Git. There is no need to install Ruby or Git when utilizing these two approaches. +### 15.1.0 + +- If you run external PostgreSQL, particularly AWS RDS, + [check you have a PostgreSQL bug fix](#postgresql-segmentation-fault-issue) + to avoid the database crashing. + ### 15.0.0 -- Elasticsearch 6.8 [is no longer supported](../integration/elasticsearch.md#version-requirements). Before you upgrade to GitLab 15.0, [update Elasticsearch to any 7.x version](../integration/elasticsearch.md#upgrade-to-a-new-elasticsearch-major-version). +- Elasticsearch 6.8 [is no longer supported](../integration/advanced_search/elasticsearch.md#version-requirements). Before you upgrade to GitLab 15.0, [update Elasticsearch to any 7.x version](../integration/advanced_search/elasticsearch.md#upgrade-to-a-new-elasticsearch-major-version). +- If you run external PostgreSQL, particularly AWS RDS, + [check you have a PostgreSQL bug fix](#postgresql-segmentation-fault-issue) + to avoid the database crashing. ### 14.10.0 -- Before upgrading to GitLab 14.10, you need to already have the latest 14.9.Z installed on your instance. +- Before upgrading to GitLab 14.10, you must already have the latest 14.9.Z installed on your instance. The upgrade to GitLab 14.10 executes a [concurrent index drop](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/84308) of unneeded entries from the `ci_job_artifacts` database table. This could potentially run for multiple minutes, especially if the table has a lot of traffic and the migration is unable to acquire a lock. It is advised to let this process finish as restarting may result in data loss. +- If you run external PostgreSQL, particularly AWS RDS, + [check you have a PostgreSQL bug fix](#postgresql-segmentation-fault-issue) + to avoid the database crashing. + +- Upgrading to patch level 14.10.3 or later might encounter a one-hour timeout due to a long running database data change, + if it was not completed while running GitLab 14.9. + + ```plaintext + FATAL: Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] + (gitlab::database_migrations line 51) had an error: + [..] + Mixlib::ShellOut::CommandTimeout: Command timed out after 3600s: + ``` + + A workaround exists to [complete the data change and the upgrade manually](package/index.md#mixlibshelloutcommandtimeout-rails_migrationgitlab-rails--command-timed-out-after-3600s). + ### 14.9.0 -- Database changes made by the upgrade to GitLab 14.9 can take hours or days to complete on larger GitLab instances. +- Database changes made by the upgrade to GitLab 14.9 can take hours or days to complete on larger GitLab instances. These [batched background migrations](#batched-background-migrations) update whole database tables to ensure corresponding records in `namespaces` table for each record in `projects` table. After you update to 14.9.0 or a later 14.9 patch version, - [batched background migrations need to finish](#batched-background-migrations) + [batched background migrations must finish](#batched-background-migrations) before you update to a later version. If the migrations are not finished and you try to update to a later version, - you'll see an error like: + you see errors like: ```plaintext Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active': ``` - + Or ```plaintext Error executing action `run` on resource 'bash[migrate gitlab-rails database]' ================================================================================ - + Mixlib::ShellOut::ShellCommandFailed ------------------------------------ - Command execution failed. STDOUT/STDERR suppressed for sensitive resource + Command execution failed. STDOUT/STDERR suppressed for sensitive resource ``` - GitLab 14.9.0 includes a @@ -461,10 +534,14 @@ and [Helm Chart deployments](https://docs.gitlab.com/charts/). They come with ap end ``` +- If you run external PostgreSQL, particularly AWS RDS, + [check you have a PostgreSQL bug fix](#postgresql-segmentation-fault-issue) + to avoid the database crashing. + ### 14.8.0 -- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. - Updating to 14.8.2 or later will reset runner registration tokens for your groups and projects. +- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. + Updating to 14.8.2 or later resets runner registration tokens for your groups and projects. - The agent server for Kubernetes [is enabled by default](https://about.gitlab.com/releases/2022/02/22/gitlab-14-8-released/#the-agent-server-for-kubernetes-is-enabled-by-default) on Omnibus installations. If you run GitLab at scale, such as [the reference architectures](../administration/reference_architectures/index.md), @@ -503,12 +580,15 @@ that may remain stuck permanently in a **pending** state. [batched migration](../user/admin_area/monitoring/background_migrations.md) named `BackfillNamespaceIdForNamespaceRoute`. You can [ignore](https://gitlab.com/gitlab-org/gitlab/-/issues/357822) this. Retry it after you upgrade to version 14.9.x. +- If you run external PostgreSQL, particularly AWS RDS, + [check you have a PostgreSQL bug fix](#postgresql-segmentation-fault-issue) + to avoid the database crashing. ### 14.7.0 - See [LFS objects import and mirror issue in GitLab 14.6.0 to 14.7.2](#lfs-objects-import-and-mirror-issue-in-gitlab-1460-to-1472). -- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. - Updating to 14.7.4 or later will reset runner registration tokens for your groups and projects. +- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. + Updating to 14.7.4 or later resets runner registration tokens for your groups and projects. - GitLab 14.7 introduced a change where Gitaly expects persistent files in the `/tmp` directory. When using the `noatime` mount option on `/tmp` in a node running Gitaly, most Linux distributions run into [an issue with Git server hooks getting deleted](https://gitlab.com/gitlab-org/gitaly/-/issues/4113). @@ -521,12 +601,15 @@ that may remain stuck permanently in a **pending** state. sudo printf "x /tmp/gitaly-%s-*\n" hooks git-exec-path >/etc/tmpfiles.d/gitaly-workaround.conf ``` + This issue is fixed in GitLab 14.10 and later when using the [Gitaly runtime directory](https://docs.gitlab.com/omnibus/update/gitlab_14_changes.html#gitaly-runtime-directory) + to specify a location to store persistent files. + ### 14.6.0 - See [LFS objects import and mirror issue in GitLab 14.6.0 to 14.7.2](#lfs-objects-import-and-mirror-issue-in-gitlab-1460-to-1472). -- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, please review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. - Updating to 14.6.5 or later will reset runner registration tokens for your groups and projects. - +- If upgrading from a version earlier than 14.6.5, 14.7.4, or 14.8.2, review the [Critical Security Release: 14.8.2, 14.7.4, and 14.6.5](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) blog post. + Updating to 14.6.5 or later resets runner registration tokens for your groups and projects. + ### 14.5.0 - When `make` is run, Gitaly builds are now created in `_build/bin` and no longer in the root directory of the source directory. If you @@ -535,17 +618,17 @@ or [init scripts](upgrading_from_source.md#configure-sysv-init-script) by [follo - Connections between Workhorse and Gitaly use the Gitaly `backchannel` protocol by default. If you deployed a gRPC proxy between Workhorse and Gitaly, Workhorse can no longer connect. As a workaround, [disable the temporary `workhorse_use_sidechannel`](../administration/feature_flags.md#enable-or-disable-the-feature) - feature flag. If you need a proxy between Workhorse and Gitaly, use a TCP proxy. If you have feedback about this change, please go to [this issue](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1301). + feature flag. If you need a proxy between Workhorse and Gitaly, use a TCP proxy. If you have feedback about this change, go to [this issue](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1301). -- In 14.1 we introduced a background migration that changes how we store merge request diff commits - in order to significantly reduce the amount of storage needed. +- In 14.1 we introduced a background migration that changes how we store merge request diff commits, + to significantly reduce the amount of storage needed. In 14.5 we introduce a set of migrations that wrap up this process by making sure that all remaining jobs over the `merge_request_diff_commits` table are completed. - These jobs will have already been processed in most cases so that no extra time is necessary during an upgrade to 14.5. + These jobs have already been processed in most cases so that no extra time is necessary during an upgrade to 14.5. However, if there are remaining jobs or you haven't already upgraded to 14.1, the deployment may take multiple hours to complete. - All merge request diff commits will automatically incorporate these changes, and there are no + All merge request diff commits automatically incorporate these changes, and there are no additional requirements to perform the upgrade. Existing data in the `merge_request_diff_commits` table remains unpacked until you run `VACUUM FULL merge_request_diff_commits`. But note that the `VACUUM FULL` operation locks and rewrites the entire `merge_request_diff_commits` table, @@ -567,10 +650,22 @@ or [init scripts](upgrading_from_source.md#configure-sysv-init-script) by [follo end ``` +- Upgrading to 14.5 (or later) [might encounter a one hour timeout](https://gitlab.com/gitlab-org/gitlab/-/issues/354211) + owing to a long running database data change. + + ```plaintext + FATAL: Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] + (gitlab::database_migrations line 51) had an error: + [..] + Mixlib::ShellOut::CommandTimeout: Command timed out after 3600s: + ``` + + [There is a workaround to complete the data change and the upgrade manually](package/index.md#mixlibshelloutcommandtimeout-rails_migrationgitlab-rails--command-timed-out-after-3600s) + ### 14.4.4 -- For [zero-downtime upgrades](zero_downtime.md) on a GitLab cluster with separate Web and API nodes, you need to enable the `paginated_tree_graphql_query` [feature flag](../administration/feature_flags.md#enable-or-disable-the-feature) _before_ upgrading GitLab Web nodes to 14.4. - This is because we [enabled `paginated_tree_graphql_query` by default in 14.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70913/diffs), so if GitLab UI is on 14.4 and its API is on 14.3, the frontend will have this feature enabled but the backend will have it disabled. This will result in the following error: +- For [zero-downtime upgrades](zero_downtime.md) on a GitLab cluster with separate Web and API nodes, you must enable the `paginated_tree_graphql_query` [feature flag](../administration/feature_flags.md#enable-or-disable-the-feature) _before_ upgrading GitLab Web nodes to 14.4. + This is because we [enabled `paginated_tree_graphql_query` by default in 14.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70913/diffs), so if GitLab UI is on 14.4 and its API is on 14.3, the frontend has this feature enabled but the backend has it disabled. This results in the following error: ```shell bundle.esm.js:63 Uncaught (in promise) Error: GraphQL error: Field 'paginatedTree' doesn't exist on type 'Repository' @@ -623,6 +718,20 @@ for how to proceed. sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production ``` +- After upgrading to 14.3, ensure that all the `MigrateMergeRequestDiffCommitUsers` background + migration jobs have completed before continuing with upgrading to GitLab 14.5 or later. + This is especially important if your GitLab instance has a large + `merge_request_diff_commits` table. Any pending + `MigrateMergeRequestDiffCommitUsers` background migration jobs are + foregrounded in GitLab 14.5, and may take a long time to complete. + You can check the count of pending jobs for + `MigrateMergeRequestDiffCommitUsers` by using the PostgreSQL console (or `sudo + gitlab-psql`): + + ```sql + select count(*) from background_migration_jobs where class_name = 'MigrateMergeRequestDiffCommitUsers' and status = 0; + ``` + - See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). ### 14.2.0 @@ -669,7 +778,7 @@ for how to proceed. - [Instances running 14.0.0 - 14.0.4 should not upgrade directly to GitLab 14.2 or later](#upgrading-to-later-14y-releases) but can upgrade to 14.1.Z. - It is not required for instances already running 14.0.5 (or higher) to stop at 14.1.Z. + It is not required for instances already running 14.0.5 (or later) to stop at 14.1.Z. 14.1 is included on the upgrade path for the broadest compatibility with self-managed installations, and ensure 14.0.0-14.0.4 installations do not encounter issues with [batched background migrations](#batched-background-migrations). @@ -694,18 +803,18 @@ Prerequisites: Long running batched background database migrations: - Database changes made by the upgrade to GitLab 14.0 can take hours or days to complete on larger GitLab instances. - These [batched background migrations](#batched-background-migrations) update whole database tables to mitigate primary key overflow and must be finished before upgrading to GitLab 14.2 or higher. + These [batched background migrations](#batched-background-migrations) update whole database tables to mitigate primary key overflow and must be finished before upgrading to GitLab 14.2 or later. - Due to an issue where `BatchedBackgroundMigrationWorkers` were [not working](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2785#note_614738345) for self-managed instances, a [fix was created](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65106) that requires an update to at least 14.0.5. The fix was also released in [14.1.0](#1410). After you update to 14.0.5 or a later 14.0 patch version, - [batched background migrations need to finish](#batched-background-migrations) + [batched background migrations must finish](#batched-background-migrations) before you update to a later version. If the migrations are not finished and you try to update to a later version, - you'll see an error like: + you see an error like: ```plaintext Expected batched background migration for the given configuration to be marked as 'finished', but it is 'active': @@ -730,7 +839,7 @@ Other issues: 1. Upgrade first to either: - 14.0.5 or a later 14.0.Z patch release. - 14.1.0 or a later 14.1.Z patch release. - 1. [Batched background migrations need to finish](#batched-background-migrations) + 1. [Batched background migrations must finish](#batched-background-migrations) before you update to a later version [and may take longer than usual](#1400). ### 13.12.0 @@ -738,7 +847,7 @@ Other issues: - See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). - Check the GitLab database [has no references to legacy storage](../administration/raketasks/storage.md#on-legacy-storage). - The GitLab 14.0 pre-install check will cause the package update to fail if there is unmigrated data: + The GitLab 14.0 pre-install check causes the package update to fail if unmigrated data exists: ```plaintext Checking for unmigrated data on legacy storage @@ -753,6 +862,15 @@ Other issues: - See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). +- GitLab 13.11 includes a faulty background migration ([`RescheduleArtifactExpiryBackfillAgain`](https://gitlab.com/gitlab-org/gitlab/-/blob/ccc70031b843ff8cff1185988c2e472a521c2701/db/post_migrate/20210413132500_reschedule_artifact_expiry_backfill_again.rb)) + that incorrectly sets the `expire_at` column in the `ci_job_artifacts` database table. + Incorrect `expire_at` values can potentially cause data loss. + + To prevent this risk of data loss, you must remove the content of the `RescheduleArtifactExpiryBackfillAgain` + migration, which makes it a no-op migration. You can repeat the changes from the + [commit that makes the migration no-op in 14.9 and later](https://gitlab.com/gitlab-org/gitlab/-/blob/42c3dfc5a1c8181767bbb5c76e7c5fa6fefbbc2b/db/post_migrate/20210413132500_reschedule_artifact_expiry_backfill_again.rb). + For more information, see [how to disable a data migration](../development/database/deleting_migrations.md#how-to-disable-a-data-migration). + ### 13.10.0 See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). @@ -837,7 +955,7 @@ DETAIL: Key (project_id, type)=(NNN, ServiceName) is duplicated. Ruby 2.7.2 is required. GitLab does not start with Ruby 2.6.6 or older versions. -The required Git version is Git v2.29 or higher. +The required Git version is Git v2.29 or later. GitLab 13.6 includes a [background migration `BackfillJiraTrackerDeploymentType2`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46368) @@ -854,7 +972,7 @@ end ### 13.4.0 -GitLab 13.4.0 includes a background migration to [move all remaining repositories in legacy storage to hashed storage](../administration/raketasks/storage.md#migrate-to-hashed-storage). There are [known issues with this migration](https://gitlab.com/gitlab-org/gitlab/-/issues/259605) which are fixed in GitLab 13.5.4 and later. If possible, skip 13.4.0 and upgrade to 13.5.4 or higher instead. Note that the migration can take quite a while to run, depending on how many repositories must be moved. Be sure to check that all background migrations have completed before upgrading further. +GitLab 13.4.0 includes a background migration to [move all remaining repositories in legacy storage to hashed storage](../administration/raketasks/storage.md#migrate-to-hashed-storage). There are [known issues with this migration](https://gitlab.com/gitlab-org/gitlab/-/issues/259605) which are fixed in GitLab 13.5.4 and later. If possible, skip 13.4.0 and upgrade to 13.5.4 or later instead. The migration can take quite a while to run, depending on how many repositories must be moved. Be sure to check that all background migrations have completed before upgrading further. ### 13.3.0 @@ -929,7 +1047,7 @@ If you persist your own Rack Attack initializers between upgrades, you might - [GitLab 13.0 requires PostgreSQL 11](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#postgresql-11-is-now-the-minimum-required-version-to-install-gitlab). - 12.10 is the final release that shipped with PostgreSQL 9.6, 10, and 11. - - You should make sure that your database is PostgreSQL 11 on GitLab 12.10 before upgrading to 13.0. This will require downtime. + - You should make sure that your database is PostgreSQL 11 on GitLab 12.10 before upgrading to 13.0. This upgrade requires downtime. ### 12.2.0 @@ -969,7 +1087,7 @@ for more information. When [Maintenance mode](../administration/maintenance_mode/index.md) is enabled, users cannot sign in with SSO, SAML, or LDAP. -Users who were signed in before Maintenance mode was enabled will continue to be signed in. If the administrator who enabled Maintenance mode loses their session, then they will not be able to disable Maintenance mode via the UI. In that case, you can [disable Maintenance mode via the API or Rails console](../administration/maintenance_mode/#disable-maintenance-mode). +Users who were signed in before Maintenance mode was enabled, continue to be signed in. If the administrator who enabled Maintenance mode loses their session, then they can't disable Maintenance mode via the UI. In that case, you can [disable Maintenance mode via the API or Rails console](../administration/maintenance_mode/#disable-maintenance-mode). [This bug](https://gitlab.com/gitlab-org/gitlab/-/issues/329261) was fixed in GitLab 14.5.0 and backported into 14.4.3 and 14.3.5. @@ -979,6 +1097,20 @@ When Geo is enabled, LFS objects fail to be saved for imported or mirrored proje [This bug](https://gitlab.com/gitlab-org/gitlab/-/issues/352368) was fixed in GitLab 14.8.0 and backported into 14.7.3. +### PostgreSQL segmentation fault issue + +If you run GitLab with external PostgreSQL, particularly AWS RDS, ensure you upgrade PostgreSQL +to patch levels to a minimum of 12.10 or 13.3 before upgrading to GitLab 14.8 or later. + +[In 14.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75511) +for GitLab Enterprise Edition and [in 15.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/87983) +for GitLab Community Edition a GitLab feature called Loose Foreign Keys was enabled. + +After it was enabled, we have had reports of unplanned PostgreSQL restarts caused +by a database engine bug that causes a segmentation fault. + +Read more [in the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/364763). + ## Miscellaneous - [MySQL to PostgreSQL](mysql_to_postgresql.md) guides you through migrating diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 40dc57c554b..8ac2791c82b 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Data Stores group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/update/package/convert_to_ee.md b/doc/update/package/convert_to_ee.md index 8a0d55e34af..34bd8e61107 100644 --- a/doc/update/package/convert_to_ee.md +++ b/doc/update/package/convert_to_ee.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/update/package/downgrade.md b/doc/update/package/downgrade.md index 81f7d089bea..7b8b4da0383 100644 --- a/doc/update/package/downgrade.md +++ b/doc/update/package/downgrade.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/update/package/index.md b/doc/update/package/index.md index faca633f446..15f43f59425 100644 --- a/doc/update/package/index.md +++ b/doc/update/package/index.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -31,6 +31,8 @@ GitLab package. upgrade is in progress. The user's web browser shows a `Deploy in progress` message or a `502` error. - For multi-node installations, see how to perform [zero downtime upgrades](../zero_downtime.md). +- Upgrades to multi-node installations can also be performed + [with downtime](../with_downtime.md). ## Version-specific changes @@ -128,7 +130,7 @@ or upgrade command: 1. Install the specific `gitlab-ee` package by using one of the following commands and replacing `<version>` with the next supported version you would like to install - (make sure to review the [upgrade path](../index.md#upgrade-paths) to confirm the + (make sure to review the [upgrade path](../index.md#upgrade-paths) to confirm the version you're installing is part of a supported path): ```shell @@ -308,3 +310,32 @@ To update the GPG key of the GitLab packages server run: curl --silent "https://packages.gitlab.com/gpg.key" | apt-key add - apt-get update ``` + +### `Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] [..] Command timed out after 3600s` + +If database schema and data changes (database migrations) must take more than one hour to run, +upgrades fail with a `timed out` error: + +```plaintext +FATAL: Mixlib::ShellOut::CommandTimeout: rails_migration[gitlab-rails] (gitlab::database_migrations line 51) +had an error: Mixlib::ShellOut::CommandTimeout: bash[migrate gitlab-rails database] +(/opt/gitlab/embedded/cookbooks/cache/cookbooks/gitlab/resources/rails_migration.rb line 16) +had an error: Mixlib::ShellOut::CommandTimeout: Command timed out after 3600s: +``` + +To fix this error: + +1. Run the remaining database migrations: + + ```shell + sudo gitlab-rake db:migrate + ``` + + This command may take a very long time to complete. Use `screen` or some other mechanism to ensure + the program is not interrupted if your SSH session drops. + +1. Complete the upgrade: + + ```shell + sudo gitlab-ctl reconfigure + ``` diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index a2d672e00ac..dc09f6063c8 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false @@ -107,7 +107,7 @@ sudo -u git -H make ### 8. Install/Update `gitlab-elasticsearch-indexer` **(PREMIUM SELF)** -Please follow the [install instruction](../integration/elasticsearch.md#install-elasticsearch). +Please follow the [install instruction](../integration/advanced_search/elasticsearch.md#install-elasticsearch). ### 9. Start application diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 99812e7fdb2..cdc3ec39f9a 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -157,10 +157,10 @@ version prior to upgrading the application server. If you're using Geo: -- Review [Geo upgrade documentation](../administration/geo/replication/updating_the_geo_sites.md). -- Read about the [Geo version-specific update instructions](../administration/geo/replication/version_specific_updates.md). -- Review Geo-specific steps when [updating the database](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). -- Create an upgrade and rollback plan for _each_ Geo node (primary and each secondary). +- Review [Geo upgrade documentation](../administration/geo/replication/upgrading_the_geo_sites.md). +- Read about the [Geo version-specific update instructions](../administration/geo/replication/version_specific_upgrades.md). +- Review Geo-specific steps when [upgrading the database](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance). +- Create an upgrade and rollback plan for _each_ Geo site (primary and each secondary). #### Runners @@ -170,7 +170,7 @@ After updating GitLab, upgrade your runners to match #### Elasticsearch After updating GitLab, you may have to upgrade -[Elasticsearch if the new version breaks compatibility](../integration/elasticsearch.md#version-requirements). +[Elasticsearch if the new version breaks compatibility](../integration/advanced_search/elasticsearch.md#version-requirements). Updating Elasticsearch is **out of scope for GitLab Support**. ## Troubleshooting diff --git a/doc/update/removals.md b/doc/update/removals.md index 4e653d5ab0a..299d1b4c341 100644 --- a/doc/update/removals.md +++ b/doc/update/removals.md @@ -4,7 +4,10 @@ group: none info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" --- -# Removals by milestone +# Removals by version + +In each release, GitLab removes features that were deprecated in an earlier release. +Some features cause breaking changes when they are removed. <!-- vale off --> @@ -28,30 +31,26 @@ For removal reviewers (Technical Writers only): https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-removals-doc --> -## 15.0 +## Removed in 15.0 ### API: `stale` status returned instead of `offline` or `not_connected` WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The Runner [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints have changed in 15.0. -A breaking change was made to the Runner [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints -in 15.0. +If a runner has not contacted the GitLab instance in more than three months, the API returns `stale` instead of `offline` or `not_connected`. +The `stale` status was introduced in 14.6. -Instead of the GitLab Runner API endpoints returning `offline` and `not_connected` for runners that have not -contacted the GitLab instance in the past three months, the API endpoints now return the `stale` value, -which was introduced in 14.6. +The `not_connected` status is no longer valid. It was replaced with `never_contacted`. Available statuses are `online`, `offline`, `stale`, and `never_contacted`. ### Audit events for repository push events WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Audit events for [repository events](https://docs.gitlab.com/ee/administration/audit_events.html#removed-events) are removed as of GitLab 15.0. @@ -63,10 +62,8 @@ Please note that we will add high-volume audit events in the future as part of [ ### Background upload for object storage WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. To reduce the overall complexity and maintenance burden of GitLab's [object storage feature](https://docs.gitlab.com/ee/administration/object_storage.html), support for using `background_upload` has been removed in GitLab 15.0. @@ -80,10 +77,8 @@ If your object storage provider does not support `background_upload`, please [mi ### Container Network and Host Security WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. All functionality related to the Container Network Security and Container Host Security categories was deprecated in GitLab 14.8 and is scheduled for removal in GitLab 15.0. Users who need a replacement for this functionality are encouraged to evaluate the following open source projects as potential solutions that can be installed and managed outside of GitLab: [AppArmor](https://gitlab.com/apparmor/apparmor), [Cilium](https://github.com/cilium/cilium), [Falco](https://github.com/falcosecurity/falco), [FluentD](https://github.com/fluent/fluentd), [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/). To integrate these technologies with GitLab, add the desired Helm charts in your copy of the [Cluster Management Project Template](https://docs.gitlab.com/ee/user/clusters/management_project_template.html). Deploy these Helm charts in production by calling commands through GitLab [CI/CD](https://docs.gitlab.com/ee/user/clusters/agent/ci_cd_workflow.html). @@ -99,10 +94,8 @@ For additional context, or to provide feedback regarding this change, please ref ### Container registry authentication with htpasswd WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The Container Registry supports [authentication](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/configuration.md#auth) with `htpasswd`. It relies on an [Apache `htpasswd` file](https://httpd.apache.org/docs/2.4/programs/htpasswd.html), with passwords hashed using `bcrypt`. @@ -134,40 +127,32 @@ The following `geo:db:*` tasks have been removed from GitLab 15.0 and have been ### DS_DEFAULT_ANALYZERS environment variable WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We are removing the `DS_DEFAULT_ANALYZERS` environment variable from Dependency Scanning on May 22, 2022 in 15.0. After this removal, this variable's value will be ignored. To configure which analyzers to run with the default configuration, you should use the `DS_EXCLUDED_ANALYZERS` variable instead. ### Dependency Scanning default Java version changed to 17 WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. For Dependency Scanning, the default version of Java that the scanner expects will be updated from 11 to 17. Java 17 is [the most up-to-date Long Term Support (LTS) version](https://en.wikipedia.org/wiki/Java_version_history). Dependency Scanning continues to support the same [range of versions (8, 11, 13, 14, 15, 16, 17)](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#supported-languages-and-package-managers), only the default version is changing. If your project uses the previous default of Java 11, be sure to [set the `DS_JAVA_VERSION` variable to match](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#configuring-specific-analyzers-used-by-dependency-scanning). Please note that consequently the default version of Gradle is now 7.3.3. -### ELK stack logging removed in GitLab 15.0 +### ELK stack logging WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The logging features in GitLab allow users to install the ELK stack (Elasticsearch, Logstash, and Kibana) to aggregate and manage application logs. Users could search for relevant logs in GitLab directly. However, since deprecating certificate-based integration with Kubernetes clusters and GitLab Managed Apps, this feature is no longer available. For more information on the future of logging and observability, you can follow the issue for [integrating Opstrace with GitLab](https://gitlab.com/groups/gitlab-org/-/epics/6976). ### Elasticsearch 6.8.x in GitLab 15.0 WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Elasticsearch 6.8 support has been removed in GitLab 15.0. Elasticsearch 6.8 has reached [end of life](https://www.elastic.co/support/eol). If you use Elasticsearch 6.8, **you must upgrade your Elasticsearch version to 7.x** prior to upgrading to GitLab 15.0. @@ -178,20 +163,16 @@ View the [version requirements](https://docs.gitlab.com/ee/integration/elasticse ### End of support for Python 3.6 in Dependency Scanning WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. For those using Dependency Scanning for Python projects, we are removing support for the default `gemnasium-python:2` image which uses Python 3.6, as well as the custom `gemnasium-python:2-python-3.9` image which uses Python 3.9. The new default image as of GitLab 15.0 will be for Python 3.9 as it is a [supported version](https://endoflife.date/python) and 3.6 [is no longer supported](https://endoflife.date/python). ### External status check API breaking changes WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The [external status check API](https://docs.gitlab.com/ee/api/status_checks.html) was originally implemented to support pass-by-default requests to mark a status check as passing. Pass-by-default requests are now removed. @@ -212,10 +193,8 @@ To align with this change, API calls to list external status checks also return ### GitLab Serverless WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. All functionality related to GitLab Serverless was deprecated in GitLab 14.3 and is scheduled for removal in GitLab 15.0. Users who need a replacement for this functionality are encouraged to explore using the following technologies with GitLab CI/CD: @@ -227,20 +206,16 @@ For additional context, or to provide feedback regarding this change, please ref ### Gitaly nodes in virtual storage WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Configuring the Gitaly nodes directly in the virtual storage's root configuration object has been deprecated in GitLab 13.12 and is no longer supported in GitLab 15.0. You must move the Gitaly nodes under the `'nodes'` key as described in [the Praefect configuration](https://docs.gitlab.com/ee/administration/gitaly/praefect.html#praefect). ### GraphQL permissions change for Package settings WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Package stage offers a Package Registry, Container Registry, and Dependency Proxy to help you manage all of your dependencies using GitLab. Each of these product categories has a variety of settings that can be adjusted using the API. @@ -253,23 +228,19 @@ The permissions model for GraphQL is being updated. After 15.0, users with the G The issue for this removal is [GitLab-#350682](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) -### Jaeger integration removed in GitLab 15.0 +### Jaeger integration WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distributed tracing system. GitLab users could previously navigate to their Jaeger instance to gain insight into the performance of a deployed application, tracking each function or microservice that handles a given request. Tracing in GitLab was deprecated in GitLab 14.7, and removed in 15.0. To track work on a possible replacement, see the issue for [Opstrace integration with GitLab](https://gitlab.com/groups/gitlab-org/-/epics/6976). ### Known host required for GitLab Runner SSH executor WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3074), we added a configuration setting in the GitLab Runner `config.toml`. This setting, [`[runners.ssh.disable_strict_host_key_checking]`](https://docs.gitlab.com/runner/executors/ssh.html#security), controls whether or not to use strict host key checking with the SSH executor. @@ -286,40 +257,32 @@ We have now removed the deprecated legacy names for approval status of license p ### Move Gitaly Cluster Praefect `database_host_no_proxy` and `database_port_no_proxy configs` WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The Gitaly Cluster configuration keys for `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']` are replaced with `praefect['database_direct_host']` and `praefect['database_direct_port']`. ### Move `custom_hooks_dir` setting from GitLab Shell to Gitaly WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The [`custom_hooks_dir`](https://docs.gitlab.com/ee/administration/server_hooks.html#create-a-global-server-hook-for-all-repositories) setting is now configured in Gitaly, and is removed from GitLab Shell in GitLab 15.0. ### OAuth implicit grant WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The OAuth implicit grant authorization flow is no longer supported. Any applications that use OAuth implicit grant must switch to alternative [supported OAuth flows](https://docs.gitlab.com/ee/api/oauth2.html). ### OAuth tokens without an expiration WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab no longer supports OAuth tokens [without an expiration](https://docs.gitlab.com/ee/integration/oauth_provider.html#expiring-access-tokens). @@ -328,10 +291,8 @@ Any existing token without an expiration has one automatically generated and app ### Optional enforcement of SSH expiration WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Disabling SSH expiration enforcement is unusual from a security perspective and could create unusual situations where an expired key is unintentionally able to be used. Unexpected behavior in a security feature is inherently dangerous and so now we enforce @@ -340,10 +301,8 @@ expiration on all SSH keys. ### Optional enforcement of personal access token expiration WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Allowing expired personal access tokens to be used is unusual from a security perspective and could create unusual situations where an expired key is unintentionally able to be used. Unexpected behavior in a security feature is inherently dangerous and so we now do not let expired personal access tokens be used. @@ -364,68 +323,11 @@ As of GitLab 15.0, we've: If you rely on Java 8 being present in the analyzer environment, you must take action as detailed in the [deprecation issue for this change](https://gitlab.com/gitlab-org/gitlab/-/issues/352549#breaking-change). -### Pseudonymizer - -WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -The Pseudonymizer feature is generally unused, can cause production issues with large databases, and can interfere with object storage development. -It was removed in GitLab 15.0. - -### Remove Versions from PackageType - -WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -As part of the work to create a [Package Registry GraphQL API](https://gitlab.com/groups/gitlab-org/-/epics/6318), the Package group deprecated the `Version` type for the basic `PackageType` type and moved it to [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#packagedetailstype). - -In GitLab 15.0, we will completely remove `Version` from `PackageType`. - -### Remove `promote-to-primary-node` command from `gitlab-ctl` - -WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-to-primary-node` which was only usable for single-node Geo sites. `gitlab-ctl promote-to-primary-node` has been removed in GitLab 15.0. - -### Remove `type` and `types` keyword from CI/CD configuration - -WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -The `type` and `types` CI/CD keywords is removed in GitLab 15.0, so pipelines that use these keywords fail with a syntax error. Switch to `stage` and `stages`, which have the same behavior. - -### Remove dependency_proxy_for_private_groups feature flag +### Pipelines field from the version field WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. - -A feature flag was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab 13.7 as part of the change to require authentication to use the Dependency Proxy. Before GitLab 13.7, you could use the Dependency Proxy without authentication. - -In GitLab 15.0, we will remove the feature flag, and you must always authenticate when you use the Dependency Proxy. - -### Remove pipelines field from the version field - -WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/#packagedetailstype) to get the pipelines for package versions: @@ -434,23 +336,20 @@ In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDeta To mitigate possible performance problems, we will remove the `versions` field's `pipelines` field in GitLab 15.0. Although you will no longer be able to get all pipelines for all versions of a package, you can still get the pipelines of a single version through the remaining `pipelines` field for that version. -### Removed feature flag PUSH_RULES_SUPERSEDE_CODE_OWNERS +### Pseudonymizer WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. -The feature flag `PUSH_RULES_SUPERSEDE_CODE_OWNERS` has been removed in GitLab 15.0. From now on, push rules will supersede CODEOWNERS. The CODEOWNERS feature is no longer available for access control. +The Pseudonymizer feature is generally unused, can cause production issues with large databases, and can interfere with object storage development. +It was removed in GitLab 15.0. ### Request profiling WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. [Request profiling](https://docs.gitlab.com/ee/administration/monitoring/performance/request_profiling.html) has been removed in GitLab 15.0. @@ -463,10 +362,8 @@ For more information, check the [summary section of the deprecation issue](https ### Required pipeline configurations in Premium tier WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. [Required pipeline configuration](https://docs.gitlab.com/ee/user/admin_area/settings/continuous_integration.html#required-pipeline-configuration) helps to define and mandate organization-wide pipeline configurations and is a requirement at an executive and organizational level. To align better with our [pricing philosophy](https://about.gitlab.com/company/pricing/#three-tiers), this feature is removed from the Premium tier in GitLab 15.0. This feature continues to be available in the GitLab Ultimate tier. @@ -480,10 +377,8 @@ This change also helps GitLab remain consistent in our tiering strategy with the ### Retire-JS Dependency Scanning tool WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We have removed support for retire.js from Dependency Scanning as of May 22, 2022 in GitLab 15.0. JavaScript scanning functionality will not be affected as it is still being covered by Gemnasium. @@ -492,10 +387,8 @@ If you have explicitly excluded retire.js using the `DS_EXCLUDED_ANALYZERS` vari ### Runner status `not_connected` API value WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Runner REST and GraphQL [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints deprecated the `not_connected` status value in GitLab 14.6 and will start returning `never_contacted` in its place @@ -527,10 +420,8 @@ If you rely on .NET 2.1 support being present in the analyzer image by default, ### SUSE Linux Enterprise Server 12 SP2 WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 SP2 [ended on March 31, 2021](https://www.suse.com/lifecycle/). The CA certificates on SP2 include the expired DST root certificate, and it's not getting new CA certificate package updates. We have implemented some [workarounds](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/merge_requests/191), but we will not be able to continue to keep the build running properly. @@ -555,10 +446,8 @@ For further details, see [the deprecation issue for this change](https://gitlab. ### Sidekiq configuration for metrics and health checks WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 15.0, you can no longer serve Sidekiq metrics and health checks over a single address and port. @@ -581,20 +470,16 @@ The Static Site Editor was deprecated in GitLab 14.7 and the feature is being re ### Support for `gitaly['internal_socket_dir']` WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Gitaly introduced a new directory that holds all runtime data Gitaly requires to operate correctly. This new directory replaces the old internal socket directory, and consequentially the usage of `gitaly['internal_socket_dir']` was deprecated in favor of `gitaly['runtime_dir']`. -### Support for legacy format of `config/database.yml` removed +### Support for legacy format of `config/database.yml` WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The syntax of [GitLab's database](https://docs.gitlab.com/omnibus/settings/database.html) configuration located in `database.yml` has changed and the legacy format has been removed. @@ -607,10 +492,8 @@ Instructions are available [in the source update documentation](https://docs.git ### Test coverage project CI/CD setting WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. To specify a test coverage pattern, in GitLab 15.0 the [project setting for test coverage parsing](https://docs.gitlab.com/ee/ci/pipelines/settings.html#add-test-coverage-results-to-a-merge-request-removed) @@ -622,32 +505,36 @@ To set test coverage parsing, use the project’s `.gitlab-ci.yml` file by provi ### The `promote-db` command is no longer available from `gitlab-ctl` WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-db` which is used to promote database nodes in multi-node Geo secondary sites. The `gitlab-ctl promote-db` command has been removed in GitLab 15.0. ### Update to the Container Registry group-level API WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 15.0, support for the `tags` and `tags_count` parameters will be removed from the Container Registry API that [gets registry repositories from a group](../api/container_registry.md#within-a-group). The `GET /groups/:id/registry/repositories` endpoint will remain, but won't return any info about tags. To get the info about tags, you can use the existing `GET /registry/repositories/:id` endpoint, which will continue to support the `tags` and `tag_count` options as it does today. The latter must be called once per image repository. +### Versions from `PackageType` + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +As part of the work to create a [Package Registry GraphQL API](https://gitlab.com/groups/gitlab-org/-/epics/6318), the Package group deprecated the `Version` type for the basic `PackageType` type and moved it to [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#packagedetailstype). + +In GitLab 15.0, we will completely remove `Version` from `PackageType`. + ### Vulnerability Check WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The vulnerability check feature was deprecated in GitLab 14.8 and is scheduled for removal in GitLab 15.0. We encourage you to migrate to the new security approvals feature instead. You can do so by navigating to **Security & Compliance > Policies** and creating a new Scan Result Policy. @@ -661,10 +548,8 @@ The new security approvals feature is similar to vulnerability check. For exampl ### `Managed-Cluster-Applications.gitlab-ci.yml` WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `Managed-Cluster-Applications.gitlab-ci.yml` CI/CD template is being removed. If you need an alternative, try the [Cluster Management project template](https://gitlab.com/gitlab-org/gitlab/-/issues/333610) instead. If your are not ready to move, you can copy the [last released version](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/v14.10.1/lib/gitlab/ci/templates/Managed-Cluster-Applications.gitlab-ci.yml) of the template into your project. @@ -675,13 +560,29 @@ keyword has been [replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/344533 [`artifacts:reports:coverage_report`](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscoverage_report). Cobertura is the only supported report file, but this is the first step towards GitLab supporting other report types. +### `defaultMergeCommitMessageWithDescription` GraphQL API field + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The GraphQL API field `defaultMergeCommitMessageWithDescription` has been removed in GitLab 15.0. For projects with a commit message template set, it will ignore the template. + +### `dependency_proxy_for_private_groups` feature flag + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +A feature flag was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) in GitLab 13.7 as part of the change to require authentication to use the Dependency Proxy. Before GitLab 13.7, you could use the Dependency Proxy without authentication. + +In GitLab 15.0, we will remove the feature flag, and you must always authenticate when you use the Dependency Proxy. + ### `omniauth-kerberos` gem WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `omniauth-kerberos` gem is no longer supported. This gem has not been maintained and has very little usage. Therefore, we removed support for this authentication method and recommend using [SPEGNO](https://en.wikipedia.org/wiki/SPNEGO) instead. You can @@ -690,47 +591,65 @@ to upgrade from the removed integration to the new supported one. We are not removing Kerberos SPNEGO integration. We are removing the old password-based Kerberos. +### `promote-to-primary-node` command from `gitlab-ctl` + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-to-primary-node` which was only usable for single-node Geo sites. `gitlab-ctl promote-to-primary-node` has been removed in GitLab 15.0. + +### `push_rules_supersede_code_owners` feature flag + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The `push_rules_supersede_code_owners` feature flag has been removed in GitLab 15.0. From now on, push rules will supersede the `CODEOWNERS` file. The code owners feature is no longer available for access control. + +### `type` and `types` keyword from CI/CD configuration + +WARNING: +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. + +The `type` and `types` CI/CD keywords is removed in GitLab 15.0, so pipelines that use these keywords fail with a syntax error. Switch to `stage` and `stages`, which have the same behavior. + ### bundler-audit Dependency Scanning tool WARNING: -This feature was changed or removed in 15.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. We are removing bundler-audit from Dependency Scanning on May 22, 2022 in 15.0. After this removal, Ruby scanning functionality will not be affected as it is still being covered by Gemnasium. If you have explicitly excluded bundler-audit using the `DS_EXCLUDED_ANALYZERS` variable, then you will be able to remove the reference to bundler-audit. If you have customized your pipeline’s Dependency Scanning configuration related to the `bundler-audit-dependency_scanning` job, then you will want to switch to `gemnasium-dependency_scanning`. If you have not used the `DS_EXCLUDED_ANALYZERS` to reference bundler-audit or customized your template specifically for bundler-audit, you will not need to take any action. -## 14.10 +## Removed in 14.10 ### Permissions change for downloading Composer dependencies WARNING: -This feature was changed or removed in 14.10 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The GitLab Composer repository can be used to push, search, fetch metadata about, and download PHP dependencies. All these actions require authentication, except for downloading dependencies. Downloading Composer dependencies without authentication is deprecated in GitLab 14.9, and will be removed in GitLab 15.0. Starting with GitLab 15.0, you must authenticate to download Composer dependencies. -## 14.9 +## Removed in 14.9 ### Integrated error tracking disabled by default WARNING: -This feature was changed or removed in 14.9 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.4, GitLab released an integrated error tracking backend that replaces Sentry. This feature caused database performance issues. In GitLab 14.9, integrated error tracking is removed from GitLab.com, and turned off by default in GitLab self-managed. While we explore the future development of this feature, please consider switching to the Sentry backend by [changing your error tracking to Sentry in your project settings](https://docs.gitlab.com/ee/operations/error_tracking.html#sentry-error-tracking). For additional background on this removal, please reference [Disable Integrated Error Tracking by Default](https://gitlab.com/groups/gitlab-org/-/epics/7580). If you have feedback please add a comment to [Feedback: Removal of Integrated Error Tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/355493). -## 14.6 +## Removed in 14.6 ### Limit the number of triggered pipeline to 25K in free tier @@ -740,7 +659,7 @@ A large amount of triggered pipelines in a single project impacts the performanc The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6. -## 14.3 +## Removed in 14.3 ### Introduced limit of 50 tags for jobs @@ -756,14 +675,14 @@ The support for [`gitlab_pages['use_legacy_storage']` setting](https://docs.gitl In 14.0 we removed [`domain_config_source`](https://docs.gitlab.com/ee/administration/pages/index.html#domain-source-configuration-before-140) which had been previously deprecated, and allowed users to specify disk storage. In 14.0 we added `use_legacy_storage` as a **temporary** flag to unblock upgrades, and allow us to debug issues with our users and it was deprecated and communicated for removal in 14.3. -## 14.2 +## Removed in 14.2 ### Max job log file size of 100 MB GitLab values efficiency for all users in our wider community of contributors, so we're always working hard to make sure the application performs at a high level with a lovable UX. In GitLab 14.2, we have introduced a [job log file size limit](https://docs.gitlab.com/ee/administration/instance_limits.html#maximum-file-size-for-job-logs), set to 100 megabytes by default. Administrators of self-managed GitLab instances can customize this to any value. All jobs that exceed this limit are dropped and marked as failed, helping prevent performance impacts or over-use of resources. This ensures that everyone using GitLab has the best possible experience. -## 14.1 +## Removed in 14.1 ### Remove support for `prometheus.listen_address` and `prometheus.enable` @@ -789,15 +708,13 @@ The minimum supported browser versions are: - Chromium 84. - Microsoft Edge 84. -## 14.0 +## Removed in 14.0 ### Auto Deploy CI template v1 WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.0, we will update the [Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/stages.html#auto-deploy) CI template to the latest version. This includes new features, bug fixes, and performance improvements with a dependency on the v2 [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image). Auto Deploy CI template v1 is deprecated going forward. @@ -806,10 +723,8 @@ Since the v1 and v2 versions are not backward-compatible, your project might enc ### Breaking changes to Terraform CI template WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab 14.0 renews the Terraform CI template to the latest version. The new template is set up for the GitLab Managed Terraform state, with a dependency on the GitLab `terraform-images` image, to provide a good user experience around GitLab's Infrastructure-as-Code features. @@ -818,10 +733,8 @@ The current stable and latest templates are not compatible, and the current late ### Code Quality RuboCop support changed WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. By default, the Code Quality feature has not provided support for Ruby 2.6+ if you're using the Code Quality template. To better support the latest versions of Ruby, the default RuboCop version is updated to add support for Ruby 2.4 through 3.0. As a result, support for Ruby 2.1, 2.2, and 2.3 is removed. You can re-enable support for older versions by [customizing your configuration](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html#rubocop-errors). @@ -830,30 +743,24 @@ Relevant Issue: [Default `codeclimate-rubocop` engine does not support Ruby 2.6+ ### Container Scanning Engine Clair WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Clair, the default container scanning engine, was deprecated in GitLab 13.9 and is removed from GitLab 14.0 and replaced by Trivy. We advise customers who are customizing variables for their container scanning job to [follow these instructions](https://docs.gitlab.com/ee/user/application_security/container_scanning/#change-scanners) to ensure that their container scanning jobs continue to work. ### DAST default template stages WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.0, we've removed the stages defined in the current `DAST.gitlab-ci.yml` template to avoid the situation where the template overrides manual changes made by DAST users. We're making this change in response to customer issues where the stages in the template cause problems when used with customized DAST configurations. Because of this removal, `gitlab-ci.yml` configurations that do not specify a `dast` stage must be updated to include this stage. ### DAST environment variable renaming and removal WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab 13.8 renamed multiple environment variables to support their broader usage in different workflows. In GitLab 14.0, the old variables have been permanently removed and will no longer work. Any configurations using these variables must be updated to the new variable names. Any scans using these variables in GitLab 14.0 and later will fail to be configured correctly. These variables are: @@ -869,10 +776,8 @@ GitLab 13.8 renamed multiple environment variables to support their broader usag ### Default Browser Performance testing job renamed in GitLab 14.0 WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Browser Performance Testing has run in a job named `performance` by default. With the introduction of [Load Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/load_performance_testing.html) in GitLab 13.2, this naming could be confusing. To make it clear which job is running [Browser Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html), the default job name is changed from `performance` to `browser_performance` in the template in GitLab 14.0. @@ -881,20 +786,16 @@ Relevant Issue: [Rename default Browser Performance Testing job](https://gitlab. ### Default DAST spider begins crawling at target URL WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab 14.0, DAST has removed the current method of resetting the scan to the hostname when starting to spider. Prior to GitLab 14.0, the spider would not begin at the specified target path for the URL but would instead reset the URL to begin crawling at the host root. GitLab 14.0 changes the default for the new variable `DAST_SPIDER_START_AT_HOST` to `false` to better support users' intention of beginning spidering and scanning at the specified target URL, rather than the host root URL. This change has an added benefit: scans can take less time, if the specified path does not contain links to the entire site. This enables easier scanning of smaller sections of an application, rather than crawling the entire app during every scan. ### Default branch name for new repositories now `main` WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Every Git repository has an initial branch, which is named `master` by default. It's the first branch to be created automatically when you create a new repository. Future [Git versions](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) will change the default branch name in Git from `master` to `main`. In coordination with the Git project and the broader community, [GitLab has changed the default branch name](https://gitlab.com/gitlab-org/gitlab/-/issues/223789) for new projects on both our SaaS (GitLab.com) and self-managed offerings starting with GitLab 14.0. This will not affect existing projects. @@ -905,10 +806,8 @@ For more information, check out our [blog post](https://about.gitlab.com/blog/20 ### Dependency Scanning WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As mentioned in [13.9](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#deprecations-for-dependency-scanning) and [this blog post](https://about.gitlab.com/blog/2021/02/08/composition-analysis-14-deprecations-and-removals/) several removals for Dependency Scanning take effect. @@ -919,10 +818,8 @@ Previously, to prevent the Gemnasium analyzers to fetch the advisory database at ### Deprecated GraphQL fields WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In accordance with our [GraphQL deprecation and removal process](https://docs.gitlab.com/ee/api/graphql/#deprecation-process), the following fields that were deprecated prior to 13.7 are [fully removed in 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/267966): @@ -936,30 +833,24 @@ In accordance with our [GraphQL deprecation and removal process](https://docs.gi ### DevOps Adoption API Segments WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The first release of the DevOps Adoption report had a concept of **Segments**. Segments were [quickly removed from the report](https://gitlab.com/groups/gitlab-org/-/epics/5251) because they introduced an additional layer of complexity on top of **Groups** and **Projects**. Subsequent iterations of the DevOps Adoption report focus on comparing adoption across groups rather than segments. GitLab 14.0 removes all references to **Segments** [from the GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/issues/324414) and replaces them with **Enabled groups**. ### Disk source configuration for GitLab Pages WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab Pages [API-based configuration](https://docs.gitlab.com/ee/administration/pages/#gitlab-api-based-configuration) has been available since GitLab 13.0. It replaces the unsupported `disk` source configuration removed in GitLab 14.0, which can no longer be chosen. You should stop using `disk` source configuration, and move to `gitlab` for an API-based configuration. To migrate away from the 'disk' source configuration, set `gitlab_pages['domain_config_source'] = "gitlab"` in your `/etc/gitlab/gitlab.rb` file. We recommend you migrate before updating to GitLab 14.0, to identify and troubleshoot any potential problems before upgrading. ### Experimental prefix in Sidekiq queue selector options WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab supports a [queue selector](https://docs.gitlab.com/ee/administration/operations/extra_sidekiq_processes.html#queue-selector) to run only a subset of background jobs for a given process. When it was introduced, this option had an 'experimental' prefix (`experimental_queue_selector` in Omnibus, `experimentalQueueSelector` in Helm charts). @@ -968,20 +859,16 @@ As announced in the [13.6 release post](https://about.gitlab.com/releases/2020/1 ### External Pipeline Validation Service Code Changes WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. For self-managed instances using the experimental [external pipeline validation service](https://docs.gitlab.com/ee/administration/external_pipeline_validation.html), the range of error codes GitLab accepts will be reduced. Currently, pipelines are invalidated when the validation service returns a response code from `400` to `499`. In GitLab 14.0 and later, pipelines will be invalidated for the `406: Not Accepted` response code only. ### Geo Foreign Data Wrapper settings WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As [announced in GitLab 13.3](https://about.gitlab.com/releases/2020/08/22/gitlab-13-3-released/#geo-foreign-data-wrapper-settings-deprecated), the following configuration settings in `/etc/gitlab/gitlab.rb` have been removed in 14.0: @@ -993,10 +880,8 @@ As [announced in GitLab 13.3](https://about.gitlab.com/releases/2020/08/22/gitla ### GitLab OAuth implicit grant WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab is deprecating the [OAuth 2 implicit grant flow](https://docs.gitlab.com/ee/api/oauth2.html#implicit-grant-flow) as it has been removed for [OAuth 2.1](https://oauth.net/2.1/). @@ -1005,30 +890,24 @@ Migrate your existing applications to other supported [OAuth2 flows](https://doc ### GitLab Runner helper image in GitLab.com Container Registry WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In 14.0, we are now pulling the GitLab Runner [helper image](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#helper-image) from the GitLab Container Registry instead of Docker Hub. Refer to [issue #27218](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27218) for details. ### GitLab Runner installation to ignore the `skel` directory WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab Runner 14.0, the installation process will ignore the `skel` directory by default when creating the user home directory. Refer to [issue #4845](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4845) for details. ### Gitaly Cluster SQL primary elector WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Now that Praefect supports a [primary election strategy](https://docs.gitlab.com/ee/administration/gitaly/praefect.html#repository-specific-primary-nodes) for each repository, we have removed the `sql` election strategy. The `per_repository` election strategy is the new default, which is automatically used if no election strategy was specified. @@ -1038,10 +917,8 @@ If you had configured the `sql` election strategy, you must follow the [migratio ### Global `SAST_ANALYZER_IMAGE_TAG` in SAST CI template WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. With the maturity of GitLab Secure scanning tools, we've needed to add more granularity to our release process. Previously, GitLab shared a major version number for [all analyzers and tools](https://docs.gitlab.com/ee/user/application_security/sast/#supported-languages-and-frameworks). This requires all tools to share a major version, and prevents the use of [semantic version numbering](https://semver.org/). In GitLab 14.0, SAST removes the `SAST_ANALYZER_IMAGE_TAG` global variable in our [managed `SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) CI template, in favor of the analyzer job variable setting the `major.minor` tag in the SAST vendored template. @@ -1052,20 +929,16 @@ This deprecation and removal changes our [previously announced plan](https://abo ### Hardcoded `master` in CI/CD templates WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Our CI/CD templates have been updated to no longer use hard-coded references to a `master` branch. In 14.0, they all use a variable that points to your project's configured default branch instead. If your CI/CD pipeline relies on our built-in templates, verify that this change works with your current configuration. For example, if you have a `master` branch and a different default branch, the updates to the templates may cause changes to your pipeline behavior. For more information, [read the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324131). ### Helm v2 support WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Helm v2 was [officially deprecated](https://helm.sh/blog/helm-v2-deprecation-timeline/) in November of 2020, with the `stable` repository being [de-listed from the Helm Hub](https://about.gitlab.com/blog/2020/11/09/ensure-auto-devops-work-after-helm-stable-repo/) shortly thereafter. With the release of GitLab 14.0, which will include the 5.0 release of the [GitLab Helm chart](https://docs.gitlab.com/charts/), Helm v2 will no longer be supported. @@ -1074,10 +947,8 @@ Users of the chart should [upgrade to Helm v3](https://helm.sh/docs/topics/v2_v3 ### Legacy DAST domain validation WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The legacy method of DAST Domain Validation for CI/CD scans was deprecated in GitLab 13.8, and is removed in GitLab 14.0. This method of domain validation only disallows scans if the `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` environment variable is set to `true` in the `gitlab-ci.yml` file, and a `Gitlab-DAST-Permission` header on the site is not set to `allow`. This two-step method required users to opt in to using the variable before they could opt out from using the header. @@ -1086,20 +957,16 @@ For more information, see the [removal issue](https://gitlab.com/gitlab-org/gitl ### Legacy feature flags WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Legacy feature flags became read-only in GitLab 13.4. GitLab 14.0 removes support for legacy feature flags, so you must migrate them to the [new version](https://docs.gitlab.com/ee/operations/feature_flags.html). You can do this by first taking a note (screenshot) of the legacy flag, then deleting the flag through the API or UI (you don't need to alter the code), and finally create a new Feature Flag with the same name as the legacy flag you deleted. Also, make sure the strategies and environments match the deleted flag. We created a [video tutorial](https://www.youtube.com/watch?v=CAJY2IGep7Y) to help with this migration. ### Legacy fields from DAST report WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As a part of the migration to a common report format for all of the Secure scanners in GitLab, DAST is making changes to the DAST JSON report. Certain legacy fields were deprecated in 13.8 and have been completely removed in 14.0. These fields are `@generated`, `@version`, `site`, and `spider`. This should not affect any normal DAST operation, but does affect users who consume the JSON report in an automated way and use these fields. Anyone affected by these changes, and needs these fields for business reasons, is encouraged to open a new GitLab issue and explain the need. @@ -1108,50 +975,40 @@ For more information, see [the removal issue](https://gitlab.com/gitlab-org/gitl ### Legacy storage WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As [announced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#planned-removal-of-legacy-storage-in-14.0), [legacy storage](https://docs.gitlab.com/ee/administration/repository_storage_types.html#legacy-storage) has been removed in GitLab 14.0. ### License Compliance WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In 13.0, we deprecated the License-Management CI template and renamed it License-Scanning. We have been providing backward compatibility by warning users of the old template to switch. Now in 14.0, we are completely removing the License-Management CI template. Read about it in [issue #216261](https://gitlab.com/gitlab-org/gitlab/-/issues/216261) or [this blog post](https://about.gitlab.com/blog/2021/02/08/composition-analysis-14-deprecations-and-removals/). ### Limit projects returned in `GET /groups/:id/` WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. To improve performance, we are limiting the number of projects returned from the `GET /groups/:id/` API call to 100. A complete list of projects can still be retrieved with the `GET /groups/:id/projects` API call. ### Make `pwsh` the default shell for newly-registered Windows Runners WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab Runner 13.2, PowerShell Core support was added to the Shell executor. In 14.0, PowerShell Core, `pwsh` is now the default shell for newly-registered Windows runners. Windows `CMD` will still be available as a shell option for Windows runners. Refer to [issue #26419](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26419) for details. ### Migrate from `SAST_DEFAULT_ANALYZERS` to `SAST_EXCLUDED_ANALYZERS` WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Until GitLab 13.9, if you wanted to avoid running one particular GitLab SAST analyzer, you needed to remove it from the [long string of analyzers in the `SAST.gitlab-ci.yml` file](https://gitlab.com/gitlab-org/gitlab/-/blob/390afc431e7ce1ac253b35beb39f19e49c746bff/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L12) and use that to set the [`SAST_DEFAULT_ANALYZERS`](https://docs.gitlab.com/ee/user/application_security/sast/#docker-images) variable in your project's CI file. If you did this, it would exclude you from future new analyzers because this string hard codes the list of analyzers to execute. We avoid this problem by inverting this variable's logic to exclude, rather than choose default analyzers. Beginning with 13.9, [we migrated](https://gitlab.com/gitlab-org/gitlab/-/blob/14fed7a33bfdbd4663d8928e46002a5ef3e3282c/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L13) to `SAST_EXCLUDED_ANALYZERS` in our `SAST.gitlab-ci.yml` file. We encourage anyone who uses a [customized SAST configuration](https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings) in their project CI file to migrate to this new variable. If you have not overridden `SAST_DEFAULT_ANALYZERS`, no action is needed. The CI/CD variable `SAST_DEFAULT_ANALYZERS` has been removed in GitLab 14.0, which released on June 22, 2021. @@ -1159,30 +1016,24 @@ Beginning with 13.9, [we migrated](https://gitlab.com/gitlab-org/gitlab/-/blob/1 ### Off peak time mode configuration for Docker Machine autoscaling WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab Runner 13.0, [issue #5069](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/5069), we introduced new timing options for the GitLab Docker Machine executor. In GitLab Runner 14.0, we have removed the old configuration option, [off peak time mode](https://docs.gitlab.com/runner/configuration/autoscale.html#off-peak-time-mode-configuration-deprecated). ### OpenSUSE Leap 15.1 WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Support for [OpenSUSE Leap 15.1 is being deprecated](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5135). Support for 15.1 will be dropped in 14.0. We are now providing support for openSUSE Leap 15.2 packages. ### PostgreSQL 11 support WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab 14.0 requires PostgreSQL 12 or later. It offers [significant improvements](https://www.postgresql.org/about/news/postgresql-12-released-1976/) to indexing, partitioning, and general performance benefits. @@ -1191,30 +1042,24 @@ Starting in GitLab 13.7, all new installations default to PostgreSQL version 12. ### Redundant timestamp field from DORA metrics API payload WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The [deployment frequency project-level API](https://docs.gitlab.com/ee/api/dora4_project_analytics.html#list-project-deployment-frequencies) endpoint has been deprecated in favor of the [DORA 4 API](https://docs.gitlab.com/ee/api/dora/metrics.html), which consolidates all the metrics under one API with the specific metric as a required field. As a result, the timestamp field, which doesn't allow adding future extensions and causes performance issues, will be removed. With the old API, an example response would be `{ "2021-03-01": 3, "date": "2021-03-01", "value": 3 }`. The first key/value (`"2021-03-01": 3`) will be removed and replaced by the last two (`"date": "2021-03-01", "value": 3`). ### Release description in the Tags API WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab 14.0 removes support for the release description in the Tags API. You can no longer add a release description when [creating a new tag](https://docs.gitlab.com/ee/api/tags.html#create-a-new-tag). You also can no longer [create](https://docs.gitlab.com/ee/api/tags.html#create-a-new-release) or [update](https://docs.gitlab.com/ee/api/tags.html#update-a-release) a release through the Tags API. Please migrate to use the [Releases API](https://docs.gitlab.com/ee/api/releases/#create-a-release) instead. ### Ruby version changed in `Ruby.gitlab-ci.yml` WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. By default, the `Ruby.gitlab-ci.yml` file has included Ruby 2.5. @@ -1225,10 +1070,8 @@ Relevant Issue: [Updates Ruby version 2.5 to 3.0](https://gitlab.com/gitlab-org/ ### SAST analyzer `SAST_GOSEC_CONFIG` variable WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. With the release of [SAST Custom Rulesets](https://docs.gitlab.com/ee/user/application_security/sast/#customize-rulesets) in GitLab 13.5 we allow greater flexibility in configuration options for our Go analyzer (GoSec). As a result we no longer plan to support our less flexible [`SAST_GOSEC_CONFIG`](https://docs.gitlab.com/ee/user/application_security/sast/#analyzer-settings) analyzer setting. This variable was deprecated in GitLab 13.10. GitLab 14.0 removes the old `SAST_GOSEC_CONFIG variable`. If you use or override `SAST_GOSEC_CONFIG` in your CI file, update your SAST CI configuration or pin to an older version of the GoSec analyzer. We strongly encourage [inheriting and overriding our managed CI templates](https://docs.gitlab.com/ee/user/application_security/sast/#overriding-sast-jobs) to future-proof your CI templates. @@ -1236,10 +1079,8 @@ GitLab 14.0 removes the old `SAST_GOSEC_CONFIG variable`. If you use or override ### Service Templates WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Service Templates are [removed in GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/5672). They were used to apply identical settings to a large number of projects, but they only did so at the time of project creation. @@ -1248,20 +1089,16 @@ While they solved part of the problem, _updating_ those values later proved to b ### Success and failure for finished build metric conversion WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab Runner 13.5, we introduced `failed` and `success` states for a job. To support Prometheus rules, we chose to convert `success/failure` to `finished` for the metric. In 14.0, the conversion has now been removed. Refer to [issue #26900](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26900) for details. ### Terraform template version WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. As we continuously [develop GitLab's Terraform integrations](https://gitlab.com/gitlab-org/gitlab/-/issues/325312), to minimize customer disruption, we maintain two GitLab CI/CD templates for Terraform: @@ -1279,10 +1116,8 @@ To check the new changes, see the [new "major version" template](https://gitlab. ### Ubuntu 16.04 support WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Ubuntu 16.04 [reached end-of-life in April 2021](https://ubuntu.com/about/release-cycle), and no longer receives maintenance updates. We strongly recommend users to upgrade to a newer release, such as 20.04. @@ -1291,90 +1126,72 @@ GitLab 13.12 will be the last release with Ubuntu 16.04 support. ### Ubuntu 19.10 (Eoan Ermine) package WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. Ubuntu 19.10 (Eoan Ermine) reached end of life on Friday, July 17, 2020. In GitLab Runner 14.0, Ubuntu 19.10 (Eoan Ermine) is no longer available from our package distribution. Refer to [issue #26036](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26036) for details. ### Unicorn in GitLab self-managed WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. [Support for Unicorn](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6078) has been removed in GitLab 14.0 in favor of Puma. [Puma has a multi-threaded architecture](https://docs.gitlab.com/ee/administration/operations/puma.html) which uses less memory than a multi-process application server like Unicorn. On GitLab.com, we saw a 40% reduction in memory consumption by using Puma. ### WIP merge requests renamed 'draft merge requests' WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The WIP (work in progress) status for merge requests signaled to reviewers that the merge request in question wasn't ready to merge. We've renamed the WIP feature to **Draft**, a more inclusive and self-explanatory term. **Draft** clearly communicates the merge request in question isn't ready for review, and makes no assumptions about the progress being made toward it. **Draft** also reduces the cognitive load for new users, non-English speakers, and anyone unfamiliar with the WIP acronym. ### Web Application Firewall (WAF) WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The Web Application Firewall (WAF) was deprecated in GitLab 13.6 and is removed from GitLab 14.0. The WAF had limitations inherent in the architectural design that made it difficult to meet the requirements traditionally expected of a WAF. By removing the WAF, GitLab is able to focus on improving other areas in the product where more value can be provided to users. Users who currently rely on the WAF can continue to use the free and open source [ModSecurity](https://github.com/SpiderLabs/ModSecurity) project, which is independent from GitLab. Additional details are available in the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271276). ### Windows Server 1903 image support WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In 14.0, we have removed Windows Server 1903. Microsoft ended support for this version on 2020-08-12. Refer to [issue #27551](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27551) for details. ### Windows Server 1909 image support WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In 14.0, we have removed Windows Server 1909. Microsoft ended support for this version on 2021-05-11. Refer to [issue #27899](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27899) for details. ### `/usr/lib/gitlab-runner` symlink from package WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In GitLab Runner 13.3, a symlink was added from `/user/lib/gitlab-runner/gitlab-runner` to `/usr/bin/gitlab-runner`. In 14.0, the symlink has been removed and the runner is now installed in `/usr/bin/gitlab-runner`. Refer to [issue #26651](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26651) for details. ### `?w=1` URL parameter to ignore whitespace changes WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. To create a consistent experience for users based on their preferences, support for toggling whitespace changes via URL parameter has been removed in GitLab 14.0. ### `CI_PROJECT_CONFIG_PATH` variable WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. The `CI_PROJECT_CONFIG_PATH` [predefined project variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) has been removed in favor of `CI_CONFIG_PATH`, which is functionally the same. @@ -1385,40 +1202,32 @@ please update them to use `CI_CONFIG_PATH` instead. ### `FF_RESET_HELPER_IMAGE_ENTRYPOINT` feature flag WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In 14.0, we have deactivated the `FF_RESET_HELPER_IMAGE_ENTRYPOINT` feature flag. Refer to issue [#26679](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26679) for details. ### `FF_SHELL_EXECUTOR_USE_LEGACY_PROCESS_KILL` feature flag WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. In [GitLab Runner 13.1](https://docs.gitlab.com/runner/executors/shell.html#gitlab-131-and-later), [issue #3376](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3376), we introduced `sigterm` and then `sigkill` to a process in the Shell executor. We also introduced a new feature flag, `FF_SHELL_EXECUTOR_USE_LEGACY_PROCESS_KILL`, so you can use the previous process termination sequence. In GitLab Runner 14.0, [issue #6413](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6413), the feature flag has been removed. ### `FF_USE_GO_CLOUD_WITH_CACHE_ARCHIVER` feature flag WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab Runner 14.0 removes the `FF_USE_GO_CLOUD_WITH_CACHE_ARCHIVER` feature flag. Refer to [issue #27175](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27175) for details. ### `secret_detection_default_branch` job WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. To ensure Secret Detection was scanning both default branches and feature branches, we introduced two separate secret detection CI jobs (`secret_detection_default_branch` and `secret_detection`) in our managed [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) template. These two CI jobs created confusion and complexity in the CI rules logic. This deprecation moves the `rule` logic into the `script` section, which then determines how the `secret_detection` job is run (historic, on a branch, commits, etc). If you override or maintain custom versions of `SAST.gitlab-ci.yml` or `Secret-Detection.gitlab-ci.yml`, you must update your CI templates. We strongly encourage [inheriting and overriding our managed CI templates](https://docs.gitlab.com/ee/user/application_security/secret_detection/#custom-settings-example) to future-proof your CI templates. GitLab 14.0 no longer supports the old `secret_detection_default_branch` job. @@ -1426,9 +1235,7 @@ If you override or maintain custom versions of `SAST.gitlab-ci.yml` or `Secret-D ### `trace` parameter in `jobs` API WARNING: -This feature was changed or removed in 14.0 -as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). -Before updating GitLab, review the details carefully to determine if you need to make any -changes to your code, settings, or workflow. +This is a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Review the details carefully before upgrading. GitLab Runner was updated in GitLab 13.4 to internally stop passing the `trace` parameter to the `/api/jobs/:id` endpoint. GitLab 14.0 deprecates the `trace` parameter entirely for all other requests of this endpoint. Make sure your [GitLab Runner version matches your GitLab version](https://docs.gitlab.com/runner/#gitlab-runner-versions) to ensure consistent behavior. diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md index cedb46a7c71..06da66088eb 100644 --- a/doc/update/restore_after_failure.md +++ b/doc/update/restore_after_failure.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index d91b3de6df1..d6548620356 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false @@ -88,7 +88,7 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ### 4. Install `gitlab-elasticsearch-indexer` **(PREMIUM SELF)** -Please follow the [install instruction](../integration/elasticsearch.md#install-elasticsearch). +Please follow the [install instruction](../integration/advanced_search/elasticsearch.md#install-elasticsearch). ### 5. Start application diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 485dbc1b0bc..29bb956cb54 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false @@ -69,9 +69,9 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --location --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.5.tar.gz" -echo '2755b900a21235b443bb16dadd9032f784d4a88f143d852bc5d154f22b8781f1 ruby-2.7.5.tar.gz' | sha256sum -c - && tar xzf ruby-2.7.5.tar.gz -cd ruby-2.7.5 +curl --remote-name --location --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby-2.7.6.tar.gz" +echo 'e7203b0cc09442ed2c08936d483f8ac140ec1c72e37bb5c401646b7866cb5d10 ruby-2.7.6.tar.gz' | sha256sum -c - && tar xzf ruby-2.7.6.tar.gz +cd ruby-2.7.6 ./configure --disable-install-rdoc --enable-shared make @@ -107,11 +107,11 @@ Download and install Go (for Linux, 64-bit): # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --location --progress-bar "https://go.dev/dl/go1.16.10.linux-amd64.tar.gz" -echo '414cd18ce1d193769b9e97d2401ad718755ab47816e13b2a1cde203d263b55cf go1.16.10.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.16.10.linux-amd64.tar.gz +curl --remote-name --location --progress-bar "https://go.dev/dl/go1.17.10.linux-amd64.tar.gz" +echo '87fc728c9c731e2f74e4a999ef53cf07302d7ed3504b0839027bd9c10edaa3fd go1.17.10.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.17.10.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,gofmt} /usr/local/bin/ -rm go1.16.10.linux-amd64.tar.gz +rm go1.17.10.linux-amd64.tar.gz ``` ### 6. Update Git @@ -346,6 +346,9 @@ upgrade instructions. ### 13. Update Gitaly +If Gitaly is located on its own server, or you use Gitaly Cluster, see [Gitaly or Gitaly Cluster](zero_downtime.md#gitaly-or-gitaly-cluster) +on the Zero downtime upgrades page. + #### Compile Gitaly ```shell diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index f2bbc8d7558..d3102ca4591 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Data Stores group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/update/with_downtime.md b/doc/update/with_downtime.md new file mode 100644 index 00000000000..9357f70e44a --- /dev/null +++ b/doc/update/with_downtime.md @@ -0,0 +1,329 @@ +--- +stage: Systems +group: Distribution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Multi-node upgrades with downtime **(FREE SELF)** + +NOTE: +This process is a work in progress. You're welcome to provide feedback by either raising a ticket to support, +or [commenting on this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6244). + +While you can upgrade a multi-node GitLab deployment [with zero downtime](zero_downtime.md), +there are a number of constraints. In particular, you can upgrade to only one minor release +at a time, for example, from 14.6 to 14.7, then to 14.8, etc. + +If you want to upgrade to more than one minor release at a time (for example, from 14.6 to 14.9), +you need to take your GitLab instance offline, which implies downtime. +Before starting this process, verify the +[version specific upgrading instructions](index.md#version-specific-upgrading-instructions) +relevant to your [upgrade path](index.md#upgrade-paths). + +For a single node installation, you only need to [uprgade the GitLab package](package/index.md). + +The process for upgrading a number of components of a multi-node GitLab +installation is the same as for zero downtime upgrades. +The differences relate to the servers running Rails (Puma/Sidekiq) and +the order of events. + +At a high level, the process is: + +1. Shut down the GitLab application. +1. Upgrade your Consul servers. +1. Upgrade the other back-end components: + - Gitaly, Rails PostgreSQL, Redis, PgBouncer: these can be upgraded in any order. + - If you use PostgreSQL or Redis from your cloud platform and upgrades are required, + substitute the instructions for Omnibus GitLab with your cloud provider's instructions. +1. Upgrade the GitLab application (Sidekiq, Puma) and start the application up. + +If you are a Community Edition user, replace `gitlab-ee` with +`gitlab-ce` in the following commands. + +## Stop writes to the database + +Shut down Puma and Sidekiq on all servers running these processes: + +```shell +sudo gitlab-ctl stop sidekiq +sudo gitlab-ctl stop puma +``` + +## Upgrade the Consul nodes + +[Consult the Consul documentation for the complete instructions](../administration/consul.md#upgrade-the-consul-nodes). + +In summary: + +1. Check the Consul nodes are all healthy. +1. Upgrade the GitLab package on all your Consul servers: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Restart all GitLab services **one node at a time**: + + ```shell + sudo gitlab-ctl restart + ``` + +If your Consul cluster processes are not on their own servers, and are shared +with another service such as Redis HA or Patroni, ensure that you follow the +following principles when upgrading those servers: + +- Do not restart services more than one server at a time. +- Check the Consul cluster is healthy before upgrading or restarting services. + +## Upgrade the Gitaly nodes (Praefect / Gitaly Cluster) + +If you're running Gitaly cluster, follow the [zero downtime process](zero_downtime.md#gitaly-or-gitaly-cluster) +for Gitaly cluster. + +If you are using Amazon Machine Images (AMIs) on AWS, the Gitaly nodes +**should not be upgraded via the AMI process**. Gitaly nodes should **only** +be upgraded using the package upgrade. This is because: + +- Praefect tracks replicas of Git repositories by server hostname. +- Redeployment using AMIs will issue the nodes with new hostnames. +- Even though the storage will be the same, Gitaly cluster will not work after this. + +The Praefect nodes, however, can be upgraded via an AMI redeployment process: + + 1. The AMI redeployment process must include `gitlab-ctl reconfigure`. + Set `praefect['auto_migrate'] = false` on the AMI so all nodes get this. This + prevents `reconfigure` from automatically running database migrations. + 1. The first node to be redeployed with the upgraded image should be your + deploy node. + 1. After it's deployed, set `praefect['auto_migrate'] = true` in `gitlab.rb` + and apply with `gitlab-ctl reconfigure`. This will run the database + migrations. + 1. Redeploy your other Praefect nodes. + +## Upgrade the Gitaly nodes not part of Gitaly cluster + +For Gitaly servers which are not part of Gitaly cluster, update the GitLab package: + +```shell +# Debian/Ubuntu +sudo apt-get update && sudo apt-get install gitlab-ee + +# Centos/RHEL +sudo yum install gitlab-ee +``` + +If you have multiple Gitaly shards or have multiple load-balanced Gitaly nodes +using NFS, it doesn't matter in which order you upgrade the Gitaly servers. + +## Upgrade the PostgreSQL nodes + +For unclustered PostgreSQL servers: + +1. Upgrade the GitLab package: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. The upgrade process does not restart PostgreSQL when the binaries are upgraded. + Restart to load the new version: + + ```shell + sudo gitlab-ctl restart + ``` + +## Upgrade the Patroni node + +Patroni is used to achiece high availabilty with PostgreSQL. + +If a PostgreSQL major version upgrade is required, +[follow the major version process](../administration/postgresql/replication_and_failover.md#upgrading-postgresql-major-version-in-a-patroni-cluster). + +The upgrade process for all other versions is performed on all replicas first. +After they're upgraded, a cluster failover occurs from the leader to one of the upgraded +replicas. This ensures that only one failover is needed, and once complete the new +leader will be upgraded. + +Follow the following process: + +1. Identify the leader and replica nodes, and [verify that the cluster is healthy](../administration/postgresql/replication_and_failover.md#check-replication-status). + Run on a database node: + + ```shell + sudo gitlab-ctl patroni members + ``` + +1. Upgrade the GitLab package on one of the replica nodes: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Restart to load the new version: + + ```shell + sudo gitlab-ctl restart + ``` + +1. [Verify that the cluster is healthy](../administration/postgresql/replication_and_failover.md#check-replication-status). +1. Repeat these steps for the other replica: upgrade, restart, health check. +1. Upgrade the leader node following the same package upgrade as the replicas. +1. Restart all services on the leader node to load the new version, and also + trigger a cluster failover: + + ```shell + sudo gitlab-ctl restart + ``` + +1. [Check the cluster is healthy](../administration/postgresql/replication_and_failover.md#check-replication-status) + +## Upgrade the PgBouncer nodes + +If you run PgBouncer on your Rails (application) nodes, then +PgBouncer are upgraded as part of the application server upgrade. + +Upgrade the PgBouncer nodes: + +```shell +# Debian/Ubuntu +sudo apt-get update && sudo apt-get install gitlab-ee + +# Centos/RHEL +sudo yum install gitlab-ee +``` + +## Upgrade the Redis node + +Upgrade a standalone Redis server by updating the GitLab package: + +```shell +# Debian/Ubuntu +sudo apt-get update && sudo apt-get install gitlab-ee + +# Centos/RHEL +sudo yum install gitlab-ee +``` + +## Upgrade Redis HA (using Sentinel) **(PREMIUM SELF)** + +Follow [the zero downtime instructions](zero_downtime.md#use-redis-ha-using-sentinel) +for upgrading your Redis HA cluster. + +## Upgrade the Rails nodes (Puma / Sidekiq) + +All the Puma and Sidekiq processes were previously shut down. On each node: + +1. Ensure `/etc/gitlab/skip-auto-reconfigure` does not exist. +1. Check that Puma and Sidekiq are shut down: + + ```shell + ps -ef | egrep 'puma: | puma | sidekiq ' + ``` + +Select one node that runs Puma. This will be your deploy node, and is responsible for +running all database migrations. On the deploy node: + +1. Ensure the server is configured to permit regular migrations. Check that + `/etc/gitlab/gitlab.rb` does not contain `gitlab_rails['auto_migrate'] = false`. + Either set it specifically `gitlab_rails['auto_migrate'] = true` or omit it + for the default behavior (`true`). + +1. If you're using PgBouncer: + + You must bypass PgBouncer and connect directly to PostgreSQL + before running migrations. + + Rails uses an advisory lock when attempting to run a migration to prevent + concurrent migrations from running on the same database. These locks are + not shared across transactions, resulting in `ActiveRecord::ConcurrentMigrationError` + and other issues when running database migrations using PgBouncer in transaction + pooling mode. + + 1. If you're running Patroni, find the leader node. Run on a database node: + + ```shell + sudo gitlab-ctl patroni members + ``` + + 1. Update `gitlab.rb` on the deploy node. Change `gitlab_rails['db_host']` + and `gitlab_rails['db_port']` to either: + + - The host and port for your database server (unclustered PostgreSQL). + - The host and port for your cluster leader if you're running Patroni. + + 1. Apply the changes: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Upgrade the GitLab package: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. If you modified `gitlab.rb` on the deploy node to bypass PgBouncer: + 1. Update `gitlab.rb` on the deploy node. Change `gitlab_rails['db_host']` + and `gitlab_rails['db_port']` back to your PgBouncer settings. + 1. Apply the changes: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. To ensure all services are running the upgraded version, and (if applicable) accessing + the database using PgBouncer, restart all services on the deploy node: + + ```shell + sudo gitlab-ctl restart + ``` + +Next, upgrade all the other Puma and Sidekiq nodes. The setting `gitlab_rails['auto_migrate']` can be +set to anything in `gitlab.rb` on these nodes. + +They can be upgraded in parallel: + +1. Upgrade the GitLab package: + + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee + + # Centos/RHEL + sudo yum install gitlab-ee + ``` + +1. Ensure all services are restarted: + + ```shell + sudo gitlab-ctl restart + ``` + +## Upgrade the Monitor node + +Upgrade the GitLab package: + +```shell +# Debian/Ubuntu +sudo apt-get update && sudo apt-get install gitlab-ee + +# Centos/RHEL +sudo yum install gitlab-ee +``` diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index 99457ef98d6..a3f9886ed0b 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -1,5 +1,5 @@ --- -stage: Enablement +stage: Systems group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -17,11 +17,16 @@ there are the following requirements: - You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. - You have set up a multi-node GitLab instance. Single-node instances do not support zero-downtime upgrades. +If you want to upgrade multiple releases or do not meet the other requirements: + +- [Upgrade a single node with downtime](package/index.md). +- [Upgrade a multi-node instance with downtime](with_downtime.md). + If you meet all the requirements above, follow these instructions in order. There are three sets of steps, depending on your deployment type: | Deployment type | Description | | --------------------------------------------------------------- | ------------------------------------------------ | -| [Gitaly Cluster](#gitaly-cluster) | GitLab CE/EE using HA architecture for Gitaly Cluster | +| [Gitaly or Gitaly Cluster](#gitaly-or-gitaly-cluster) | GitLab CE/EE using HA architecture for Gitaly or Gitaly Cluster | | [Multi-node / PostgreSQL HA](#use-postgresql-ha) | GitLab CE/EE using HA architecture for PostgreSQL | | [Multi-node / Redis HA](#use-redis-ha-using-sentinel) | GitLab CE/EE using HA architecture for Redis | | [Geo](#geo-deployment) | GitLab EE with Geo enabled | @@ -176,66 +181,84 @@ load balancer to latest GitLab version. sudo gitlab-rake db:migrate ``` -### Gitaly Cluster +### Gitaly or Gitaly Cluster -[Gitaly Cluster](../administration/gitaly/praefect.md) is built using -Gitaly and the Praefect component. It has its own PostgreSQL database, independent of the rest of -the application. +Gitaly nodes can be located on their own server, either as part of a sharded setup, or as part of +[Gitaly Cluster](../administration/gitaly/praefect.md). -Before you update the main application you need to update Praefect. -Out of your Praefect nodes, pick one to be your Praefect deploy node. -This is where you install the new Omnibus package first and run -database migrations. +Before you update the main GitLab application you must (in order): -**Praefect deploy node** +1. Upgrade the Gitaly nodes that reside on separate servers. +1. Upgrade Praefect if using Gitaly Cluster. -- Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, which by default automatically stops GitLab, runs all database migrations, and restarts GitLab: +#### Upgrade Gitaly nodes - ```shell - sudo touch /etc/gitlab/skip-auto-reconfigure - ``` +Upgrade the Gitaly nodes one at a time to ensure access to Git repositories is maintained: -- Ensure that `praefect['auto_migrate'] = true` is set in `/etc/gitlab/gitlab.rb` +```shell +# Debian/Ubuntu +sudo apt-get update && sudo apt-get install gitlab-ee -**All Praefect nodes _excluding_ the Praefect deploy node** +# Centos/RHEL +sudo yum install gitlab-ee +``` -- To prevent `reconfigure` from automatically running database migrations, ensure that `praefect['auto_migrate'] = false` is set in `/etc/gitlab/gitlab.rb`. +If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command. -**Praefect deploy node** +#### Upgrade Praefect -- Update the GitLab package: +From the Praefect nodes, select one to be your Praefect deploy node. You install the new Omnibus package on the deploy +node first and run database migrations. - ```shell - # Debian/Ubuntu - sudo apt-get update && sudo apt-get install gitlab-ee +1. On the **Praefect deploy node**: - # Centos/RHEL - sudo yum install gitlab-ee - ``` + 1. Create an empty file at `/etc/gitlab/skip-auto-reconfigure`. This prevents upgrades from running `gitlab-ctl reconfigure`, + which by default automatically stops GitLab, runs all database migrations, and restarts GitLab: - If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command. + ```shell + sudo touch /etc/gitlab/skip-auto-reconfigure + ``` -- To apply the Praefect database migrations and restart Praefect, run: + 1. Ensure that `praefect['auto_migrate'] = true` is set in `/etc/gitlab/gitlab.rb`. - ```shell - sudo gitlab-ctl reconfigure - ``` +1. On all **remaining Praefect nodes**, ensure that `praefect['auto_migrate'] = false` is + set in `/etc/gitlab/gitlab.rb` to prevent `reconfigure` from automatically running database migrations. -**All Praefect nodes _excluding_ the Praefect deploy node** +1. On the **Praefect deploy node**: -- Update the GitLab package: + 1. Upgrade the GitLab package: - ```shell - sudo apt-get update && sudo apt-get install gitlab-ee - ``` + ```shell + # Debian/Ubuntu + sudo apt-get update && sudo apt-get install gitlab-ee - If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the above command. + # Centos/RHEL + sudo yum install gitlab-ee + ``` -- Ensure nodes are running the latest code: + If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the command above. - ```shell - sudo gitlab-ctl reconfigure - ``` + 1. To apply the Praefect database migrations and restart Praefect, run: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. On all **remaining Praefect nodes**: + + 1. Upgrade the GitLab package: + + ```shell + sudo apt-get update && sudo apt-get install gitlab-ee + ``` + + If you are a Community Edition user, replace `gitlab-ee` with `gitlab-ce` in the command above. + + 1. Ensure nodes are running the latest code: + + ```shell + sudo gitlab-ctl reconfigure + ``` ### Use PostgreSQL HA @@ -290,7 +313,7 @@ node throughout the process. - If you're using PgBouncer: - You need to bypass PgBouncer and connect directly to the database master + You need to bypass PgBouncer and connect directly to the database leader before running migrations. Rails uses an advisory lock when attempting to run a migration to prevent @@ -299,7 +322,7 @@ node throughout the process. and other issues when running database migrations using PgBouncer in transaction pooling mode. - To find the master node, run the following on a database node: + To find the leader node, run the following on a database node: ```shell sudo gitlab-ctl patroni members @@ -307,7 +330,7 @@ node throughout the process. Then, in your `gitlab.rb` file on the deploy node, update `gitlab_rails['db_host']` and `gitlab_rails['db_port']` with the database - master's host and port. + leader's host and port. - To get the regular database migrations and latest code in place, run @@ -589,7 +612,7 @@ You can only upgrade one minor release at a time. This section describes the steps required to upgrade a multi-node / HA deployment with Geo. Some steps must be performed on a particular node. This -node is known as the “deploy node” and is noted through the following +node is known as the "deploy node" and is noted through the following instructions. Updates must be performed in the following order: @@ -673,7 +696,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure 1. If you're using PgBouncer: - You need to bypass PgBouncer and connect directly to the database master + You need to bypass PgBouncer and connect directly to the database leader before running migrations. Rails uses an advisory lock when attempting to run a migration to prevent @@ -682,7 +705,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure and other issues when running database migrations using PgBouncer in transaction pooling mode. - To find the master node, run the following on a database node: + To find the leader node, run the following on a database node: ```shell sudo gitlab-ctl patroni members @@ -690,7 +713,7 @@ sudo touch /etc/gitlab/skip-auto-reconfigure Then, in your `gitlab.rb` file on the deploy node, update `gitlab_rails['db_host']` and `gitlab_rails['db_port']` with the database - master's host and port. + leader's host and port. 1. To get the regular database migrations and latest code in place, run |