You are viewing **Develocity Documentation 2025.4**. To view the latest available version of the docs, see [2026.1](https://docs.gradle.com/develocity/2026.1/operations/upgrade/). # 2025.4 Develocity Upgrade Guide ## 1. Overview Upgrading to a new version of Develocity provides your organization with new features, improved functionality, and security updates. This page provides the steps to upgrade Develocity from version **2025.3** to version **2025.4**. > [!WARNING] > If you are upgrading from a version older than 2025.3, refer to the 2025.3 Upgrade Guide and address all changes before proceeding with this guide. ## 2. Changes This section details specific changes introduced in this release that require your attention or action during the upgrade process. Review each item carefully to ensure a smooth and successful transition. ### 2.1. Moving off-heap memory configuration to Helm values (since 2025.3.3) To better support separation of duties between Develocity administrators and cluster operators, a cluster operator can now opt in to configure Java off-heap memory for the `enterprise` and `testDistribution` components, and for the `enterpriseBackgroundProcessor` component if enabled, as Helm values by specifying: **values.yaml:** ``` enterprise: resources: jvm: memory: offHeap: 512 (1) testDistribution: resources: jvm: memory: offHeap: 512 (2) enterpriseBackgroundProcessor: resources: jvm: memory: offHeap: 512 (3) ``` 1. Taken from Administration/Advanced, section Application, Off heap memory (MiB) value in the UI 2. Taken from Administration/Advanced, section Test Distribution broker, Off heap memory (MiB) value in the UI 3. Taken from Administration/Advanced, section Background processor, Off heap memory (MiB) value in the UI This allows a cluster operator to configure related memory settings in one place (Helm values). When configured via Helm, the ability for Develocity administrators to configure ‘Off-heap memory (MiB)’ in the ‘Administration/Advanced’ user interface or in the enterprise configuration file is disabled for the selected components. Existing values in these locations are silently ignored. If the Off heap memory is configured as Helm value and a unattended configuration file is used, please consider removing these settings from the unattended configuration file. ### 2.2. `gradle-monitoring` subcomponent is modified The metric-scraper component used inside `gradle-monitoring` has been replaced by a new one that consumes less CPU and Memory. We encourage you to delete/reset all configuration in your `values.yaml`, under `monitoring.scraper.*`, to go back to the default configuration for this subcomponent. Finally, that component is bundled in a new image (`registry.gradle.com/develocity/monitoring-vmagent`), and you should adjust your infrastructure or installation process to reflect this addition (image cache or registry, firewall rules for image download, etc). ### 2.3. `gradle-monitoring` Subcomponent for Logs Is Modified The log-collector component used inside `gradle-monitoring` has been replaced by a maintained new one that consumes less CPU and Memory. That component is bundled in a new image (`registry.gradle.com/develocity/monitoring-vector`), and you should adjust your infrastructure or installation process to reflect this addition (image cache or registry, firewall rules for image download, etc). ## 3. Compatibility Table The versions below were confirmed to work with Develocity 2025.4.
Supported software versions
SoftwareMinimum versionLatest version
Kubernetes1.30.01.35.3
Helm3.17.04.1.4
PostgreSQL15, 14 deprecated17, 18 for 2025.4.1+
Check the [version overview matrix](https://docs.gradle.com/develocity/2025.4/miscellaneous/compatibility/#kubernetes_and_helm) for a full overview of the version compatibility of Develocity with related components. ## 4. User-Managed Database For major version upgrades (for example, _2025.3_ to _2025.4_), if data is stored in a user-managed database and superuser credentials are not supplied, the database setup script must be run **before** the upgrade. The corresponding script for Develocity 2025.4 can be downloaded via the following link **2025.4** — * [Download Database Setup Scripts](https://docs.gradle.com/downloads/gradle-enterprise-database-setup-zip/gradle-enterprise-database-setup-zip-2025.4.zip) * [Download SHA256 Checksum](https://docs.gradle.com/downloads/gradle-enterprise-database-setup-zip/gradle-enterprise-database-setup-zip-2025.4.zip.sha256) > [!NOTE] > Looking for an older version? You can find downloads for previous releases in our legacy documentation archive. **Depending on the size of your database, it may take from a few minutes to up to hours.** > [!WARNING] > It’s strongly recommend to make a database backup before upgrading. Upgrading Develocity irreversibly changes the database schema. You will need to restore the database from a backup if you need to roll back the upgrade. ## 5. Standalone ### 5.1. Online #### 5.1.1. Upgrade K3s Running the following command will: * Download the latest k3s binary supported by Develocity 2025.4. * Restart the k3s service. ```shell curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.35.3+k3s1 sh - ``` For more information, see the official [K3s upgrade documentation](https://docs.k3s.io/upgrades/manual). > [!NOTE] > At this point, you still run the old version of Develocity. Please confirm it works as expected before proceeding with the upgrade. Accessing the application and verifying it receives new Build Scan data is the easiest method. #### 5.1.2. Upgrade Helm Running the following commands will: * Download the Helm installation script. * Set the permissions of the script. Only the owner has read, write, and execute permissions. * Install the Helm version specified with the `-v` flag. ```shell curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 ``` ```shell chmod 700 get_helm.sh ``` ```shell ./get_helm.sh -v v4.1.4 ``` For more information, see the official [Helm installation](https://helm.sh/docs/intro/install/) documentation. Verify that `helm` is installed and working: ```shell helm version ``` #### 5.1.3. Upgrade Develocity ##### Update Repository First, run the `helm repo update gradle` command to update locally available charts: ```shell helm repo update gradle ``` ##### Adjust values.yaml Configuration Adjust your `values.yaml` configuration file. You can find a detailed list of required changes in the [Required Changes](#required_changes) section. You can discover your current configuration by running the following command: ```shell helm get values \ --namespace develocity \(1) ge-standalone \(2) > values.yaml (3) ``` 1. The namespace used to install Develocity. 2. Release name. 3. Output file. ##### Adjust Unattended Configuration If you are using [unattended configuration](https://docs.gradle.com/develocity/2025.4/administration/admin-manual/#configuring_develocity_for_unattended_configuration), export the current configuration using the Admin UI. Then adjust the exported configuration according to the [Required Changes](#required_changes) section. You can validate your unattended configuration against the schema by using the [Develocity command line tool](https://docs.gradle.com/develocity/develocityctl/1.22/) (develocityctl): ```shell develocityctl config-file validate unattended-configuration.yaml ``` If your unattended configuration is embedded in the `values.yaml` file, you can validate it with the following command: ```shell cat values.yaml | yq '.global.unattended.configuration' | develocityctl config-file validate - ``` > [!NOTE] > Unattended configuration is versioned. If an older version is provided, the application migrates the config to the latest version automatically. If you use version control, it’s recommended that you export your unattended configuration after the upgrade and store the latest version in your repository. See Migrating Unattended Configuration for details. ##### Decide on the Upgrade Command You may need to run different upgrade commands depending on your configuration changes. You can find recommendations in the [Upgrade Command Explained](#upgrade_command) section. ##### Use `dry-run` to Verify the Upgrade Before upgrading, you can use the `--dry-run` flag to verify the upgrade process. This will show you the changes that would be made without actually applying them. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ --version 2025.4.5 \ ge-standalone \ gradle/gradle-enterprise-standalone \ --dry-run ``` > [!NOTE] > The actual command may differ depending on the outcome from the previous step. > [!WARNING] > If the --dry-run command completes successfully, you can proceed with the upgrade. Otherwise, review the output and make any necessary changes to your configuration. --dry-run validates syntax, verifies the chart structure, validates your configuration with schema, and checks the generated Kubernetes manifests for errors. However, it won’t detect issues like typos in optional fields or guarantee the application configuration will function correctly. ##### Execute the Upgrade Remove `--dry-run` from the command above and execute the upgrade. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ --version 2025.4.5 \ ge-standalone \ gradle/gradle-enterprise-standalone ``` ### 5.2. Airgap Upgrading an airgap instance of Develocity requires downloading the latest version of charts, transferring them to the host machine, and installing them. Downloading an update for Develocity requires your license file. > [!WARNING] > If you use `helm template` (or `--reset-values`), you must specify all installation options again, including files. You must transfer these files to the machine used to access the cluster. #### 5.2.1. Download Required Files ##### Download K3s Running the following commands will: * Download the K3s binary. * Download the K3s airgap image. * Download the K3s installation script. Download the K3s binary: ```shell curl -LO https://github.com/k3s-io/k3s/releases/download/v1.35.3+k3s1/k3s ``` Download the K3s airgap image: ```shell curl -LO \ https://github.com/k3s-io/k3s/releases/download/v1.35.3%2Bk3s1/k3s-airgap-images-amd64.tar.gz ``` Download the K3s installation script: ```shell curl -L -o install_k3s.sh https://get.k3s.io ``` If you are running Red Hat Enterprise Linux with SELinux enabled, download the K3s policy package: **SELinux policy package download** Lookup the latest version of the K3s SELinux Policy package: ```shell K3S_SELINUX_DOWNLOAD_URL=$(curl -s https://api.github.com/repos/k3s-io/k3s-selinux/releases/latest | jq -r '.assets[] | select( .name | endswith("el8.noarch.rpm") ) | .browser_download_url') && echo $K3S_SELINUX_DOWNLOAD_URL ``` > [!NOTE] > You can view the versions available and find the download links on the K3s SELinux [releases page](https://github.com/k3s-io/k3s-selinux/releases). Then download it: ```shell curl -L -o k3s-selinux.el8.noarch.rpm $K3S_SELINUX_DOWNLOAD_URL ``` ##### Download Helm Download the Helm binary: ```shell curl -L -o helm-linux-amd64.tar.gz https://get.helm.sh/helm-v4.1.4-linux-amd64.tar.gz ``` ##### Download Airgap Bundle Save your Develocity license to the transfer directory as `develocity.license`. Download and verify the airgap bundle: ```shell curl -LOJd @develocity.license \ https://registry.gradle.com/airgap/gradle-enterprise-standalone-2025.4.5-bundle.tar.gz ``` ```shell curl -LOJd @develocity.license \ https://registry.gradle.com/airgap/gradle-enterprise-standalone-2025.4.5-bundle.tar.gz.sha256 ``` ```shell sha256sum -c gradle-enterprise-standalone-2025.4.5-bundle.tar.gz.sha256 ``` If the checksum verification fails, check the contents of the downloaded files for error messages. If the error message indicates that your license is invalid/expired/not airgap enabled, you will need to request an updated license file by contacting your customer success representative. > [!TIP] > Instead of running the above `curl` commands, you can download the airgap bundle by navigating to [https://registry.gradle.com/airgap](https://registry.gradle.com/airgap) in your browser and following the instructions on the page. #### 5.2.2. Transfer Files Check that the transfer directory has the following files (additional files are fine): * `k3s-airgap-images-amd64.tar.gz` * `k3s` * `install_k3s.sh` * `k3s-selinux.el8.noarch.rpm` (only if you are running SELinux) * `helm-linux-amd64.tar.gz` * `gradle-enterprise-standalone-2025.4.5-bundle.tar.gz` Once you’ve verified that you have the required files, transfer them to the host where you are installing Develocity. #### 5.2.3. Import the New Container Images The new Develocity images must be imported into K3s’s embedded container registry. Run the following commands to: * Unpack the airgap bundle. * Imports Develocity’s images into K3s. ```shell tar zxvf gradle-enterprise-standalone-2025.4.5-bundle.tar.gz ``` ```shell sudo k3s ctr images import gradle-enterprise-standalone-2025.4.5-images.tar ``` #### 5.2.4. Upgrade K3s Follow these instructions on the host where you install Develocity with your transferred files in the current directory. If you are running Red Hat Enterprise Linux with SELinux enabled, first install the necessary policy packages: **SELinux Policy installation** ##### Install the `container-selinux` Package Install the K3s SELinux Policy package you downloaded: ```shell sudo yum install -y k3s-selinux.el9.noarch.rpm ``` Install K3s and make it available to the current user: ```shell sudo mkdir -p /var/lib/rancher/k3s/agent/images/ && \ sudo cp k3s-airgap-images-amd64.tar.gz /var/lib/rancher/k3s/agent/images/ ``` ```shell (cd /var/lib/rancher/k3s/agent/images/ && sudo gunzip -f k3s-airgap-images-amd64.tar.gz) ``` ```shell sudo cp k3s /usr/local/bin && sudo chmod a+rx /usr/local/bin/k3s ``` ```shell sudo chmod a+rx ./install_k3s.sh && INSTALL_K3S_SKIP_DOWNLOAD=true ./install_k3s.sh ``` ```shell sudo chown $UID /etc/rancher/k3s/k3s.yaml && \ mkdir -p "${HOME}/.kube" && \ ln -sf /etc/rancher/k3s/k3s.yaml "${HOME}/.kube/config" ``` Verify that you can interact with the K3s cluster: ```shell kubectl get namespace ``` **Output:** ``` NAME STATUS AGE default Active 1h kube-system Active 1h kube-public Active 1h kube-node-lease Active 1h develocity Active 1h ``` > [!NOTE] > At this point, you still run the old version of Develocity. Please confirm it works as expected before proceeding with the upgrade. Accessing the application and verifying it receives new Build Scan data is the easiest method. #### 5.2.5. Upgrade Helm Follow these instructions on the host where you are installing Develocity with your transferred files present in the current directory. Run the following commands to unpack and install Helm: ```shell tar -zxvf helm-linux-amd64.tar.gz && sudo mv linux-amd64/helm /usr/local/bin/helm ``` Verify that `helm` is installed and working: ```shell helm version ``` #### 5.2.6. Upgrade Develocity ##### Adjust values.yaml Configuration Adjust your `values.yaml` configuration file. You can find a detailed list of required changes in the [Required Changes](#required_changes) section. You can discover your current configuration by running the following command: ```shell helm get values \ --namespace develocity \(1) ge-standalone \(2) > values.yaml (3) ``` 1. The namespace used to install Develocity. 2. Release name. 3. Output file. ##### Adjust Unattended Configuration If you are using [unattended configuration](https://docs.gradle.com/develocity/2025.4/administration/admin-manual/#configuring_develocity_for_unattended_configuration), export the current configuration using the Admin UI. Then adjust the exported configuration according to the [Required Changes](#required_changes) section. You can validate your unattended configuration against the schema by using the [Develocity command line tool](https://docs.gradle.com/develocity/develocityctl/1.22/) (develocityctl): ```shell develocityctl config-file validate unattended-configuration.yaml ``` If your unattended configuration is embedded in the `values.yaml` file, you can validate it with the following command: ```shell cat values.yaml | yq '.global.unattended.configuration' | develocityctl config-file validate - ``` > [!NOTE] > Unattended configuration is versioned. If an older version is provided, the application migrates the config to the latest version automatically. If you use version control, it’s recommended that you export your unattended configuration after the upgrade and store the latest version in your repository. See Migrating Unattended Configuration for details. ##### Decide on the Upgrade Command You may need to run different upgrade commands depending on your configuration changes. You can find recommendations in the [Upgrade Command Explained](#upgrade_command) section. ##### Use `dry-run` to Verify the Upgrade Before upgrading, you can use the `--dry-run` flag to verify the upgrade process. This will show you the changes that would be made without actually applying them. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ ge-standalone \ gradle-enterprise-standalone-2025.4.5.tgz \ --dry-run ``` > [!NOTE] > The actual command may differ depending on the outcome from the previous step. > [!WARNING] > If the --dry-run command completes successfully, you can proceed with the upgrade. Otherwise, review the output and make any necessary changes to your configuration. --dry-run validates syntax, verifies the chart structure, validates your configuration with schema, and checks the generated Kubernetes manifests for errors. However, it won’t detect issues like typos in optional fields or guarantee the application configuration will function correctly. ##### Execute the Upgrade Remove `--dry-run` from the command above and execute the upgrade. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ ge-standalone \ gradle-enterprise-standalone-2025.4.5.tgz ``` ## 6. Kubernetes _Kubernetes installation type is for advanced users. This section assumes that you have a base knowledge of Kubernetes._ ### 6.1. Upgrading With Multiple Replicas If you have configured more than one replica, you must scale the replicas down to one before upgrading to avoid having mixed versions running simultaneously. > [!WARNING] > Before applying the upgrade, run the following command to scale the application down to one replica. #### 6.1.1. Scale Down the Application to One Replica ```shell helm upgrade \ --namespace develocity \ --reuse-values \ --set=global.scaling.replicas=1 \ --version «PREVIOUSLY_DEPLOYED_VERSION» \(1) ge gradle/gradle-enterprise (2) ``` 1. «PREVIOUSLY_DEPLOYED_VERSION» is the running version of Develocity (e.g. 2025.3.3), not the version you are upgrading to. 2. Replace gradle/gradle-enterprise with gradle-enterprise-2025.3.3.tgz for airgap installations. #### 6.1.2. Upgrade Develocity Use [online](#kubernetes_upgrade_online) or [airgap](#kubernetes_upgrade_airgap) instructions below to upgrade Develocity. #### 6.1.3. Scale up the Application to N Replicas > [!NOTE] > Before you scale up the application, ensure the upgrade went well and the application is working. ```shell helm upgrade \ --namespace develocity \ --reuse-values \ --set=global.scaling.replicas=N \(1) --version «NEWLY_DEPLOYED_VERSION» \(2) gradle/gradle-enterprise (3) ``` 1. N is the number of replicas you want to scale up to. 2. «NEWLY_DEPLOYED_VERSION» is the version of Develocity you just upgraded to (e.g. 2025.4.5). 3. Replace gradle/gradle-enterprise with gradle-enterprise-2025.4.5.tgz for airgap installations. ### 6.2. Online #### 6.2.1. Upgrade Helm Running the following commands will: * Download the Helm installation script. * Set the permissions of the script. Only the owner has read, write, and execute permissions. * Install the Helm version specified with the `-v` flag. ```shell curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 ``` ```shell chmod 700 get_helm.sh ``` ```shell ./get_helm.sh -v v4.1.4 ``` For more information, see the official [Helm installation](https://helm.sh/docs/intro/install/) documentation. Verify that `helm` is installed and working: ```shell helm version ``` #### 6.2.2. Upgrade Develocity ##### Update Repository First, run the `helm repo update gradle` command to update locally available charts: ```shell helm repo update gradle ``` ##### Adjust values.yaml Configuration Adjust your `values.yaml` configuration file. You can find a detailed list of required changes in the [Required Changes](#required_changes) section. You can discover your current configuration by running the following command: ```shell helm get values \ --namespace develocity \(1) ge \(2) > values.yaml (3) ``` 1. The namespace used to install Develocity. 2. Release name. 3. Output file. ##### Adjust Unattended Configuration If you are using [unattended configuration](https://docs.gradle.com/develocity/2025.4/administration/admin-manual/#configuring_develocity_for_unattended_configuration), export the current configuration using the Admin UI. Then adjust the exported configuration according to the [Required Changes](#required_changes) section. You can validate your unattended configuration against the schema by using the [Develocity command line tool](https://docs.gradle.com/develocity/develocityctl/1.22/) (develocityctl): ```shell develocityctl config-file validate unattended-configuration.yaml ``` If your unattended configuration is embedded in the `values.yaml` file, you can validate it with the following command: ```shell cat values.yaml | yq '.global.unattended.configuration' | develocityctl config-file validate - ``` > [!NOTE] > Unattended configuration is versioned. If an older version is provided, the application migrates the config to the latest version automatically. If you use version control, it’s recommended that you export your unattended configuration after the upgrade and store the latest version in your repository. See Migrating Unattended Configuration for details. ##### Decide on the Upgrade Command You may need to run different upgrade commands depending on your configuration changes. You can find recommendations in the [Upgrade Command Explained](#upgrade_command) section. ##### Use `dry-run` to Verify the Upgrade Before upgrading, you can use the `--dry-run` flag to verify the upgrade process. This will show you the changes that would be made without actually applying them. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ --version 2025.4.5 \ ge \ gradle/gradle-enterprise \ --dry-run ``` > [!NOTE] > The actual command may differ depending on the outcome from the previous step. > [!WARNING] > If the --dry-run command completes successfully, you can proceed with the upgrade. Otherwise, review the output and make any necessary changes to your configuration. --dry-run validates syntax, verifies the chart structure, validates your configuration with schema, and checks the generated Kubernetes manifests for errors. However, it won’t detect issues like typos in optional fields or guarantee the application configuration will function correctly. ##### Execute the Upgrade Remove `--dry-run` from the command above and execute the upgrade. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ --version 2025.4.5 \ ge \ gradle/gradle-enterprise ``` ### 6.3. Airgap Upgrading an airgap instance of Develocity requires downloading the latest version of charts, transferring them to the host machine, and installing them. Downloading an update for Develocity requires your license file. > [!WARNING] > If you use `helm template` (or `--reset-values`), you must specify all installation options again, including files. You must transfer these files to the machine used to access the cluster. #### 6.3.1. Download Required Files ##### Download Helm Download the Helm binary: ```shell curl -L -o helm-linux-amd64.tar.gz https://get.helm.sh/helm-v4.1.4-linux-amd64.tar.gz ``` ##### Download Airgap Bundle Save your Develocity license to the transfer directory as `develocity.license`. Download and verify the airgap bundle: ```shell curl -LOJd @develocity.license \ https://registry.gradle.com/airgap/gradle-enterprise-2025.4.5-bundle.tar.gz ``` ```shell curl -LOJd @develocity.license \ https://registry.gradle.com/airgap/gradle-enterprise-2025.4.5-bundle.tar.gz.sha256 ``` ```shell sha256sum -c gradle-enterprise-2025.4.5-bundle.tar.gz.sha256 ``` If the checksum verification fails, check the contents of the downloaded files for error messages. If the error message indicates that your license is invalid/expired/not airgap enabled, you will need to request an updated license file by contacting your customer success representative. > [!TIP] > Instead of running the above `curl` commands, you can download the airgap bundle by navigating to [https://registry.gradle.com/airgap](https://registry.gradle.com/airgap) in your browser and following the instructions on the page. #### 6.3.2. Transfer Files Check that the transfer directory has the following files (additional files are fine): * `helm-linux-amd64.tar.gz` * `gradle-enterprise-2025.4.5-bundle.tar.gz` Once you’ve verified that you have the required files, transfer them to the host where you are installing Develocity. #### 6.3.3. Upload Images Follow these instructions on the host with connectivity to the internal container registry with your transferred files present in the current directory. > [!NOTE] > You must be logged in to the registry before running these commands. Run the following commands to unpack the bundle and upload the images to the internal container registry: ```shell tar zxvf gradle-enterprise-2025.4.5-bundle.tar.gz ``` ```shell ./upload-images.sh --registry=registry.example.com/gradle-enterprise ``` #### 6.3.4. Upgrade Helm Follow these instructions on the host with connectivity to the Kubernetes cluster with your transferred files present in the current directory. Run the following commands to unpack and install Helm: ```shell tar -zxvf helm-linux-amd64.tar.gz && sudo mv linux-amd64/helm /usr/local/bin/helm ``` Verify that `helm` is installed and working: ```shell helm version ``` #### 6.3.5. Upgrade Develocity ##### Adjust values.yaml Configuration Adjust your `values.yaml` configuration file. You can find a detailed list of required changes in the [Required Changes](#required_changes) section. You can discover your current configuration by running the following command: ```shell helm get values \ --namespace develocity \(1) ge \(2) > values.yaml (3) ``` 1. The namespace used to install Develocity. 2. Release name. 3. Output file. ##### Adjust Unattended Configuration If you are using [unattended configuration](https://docs.gradle.com/develocity/2025.4/administration/admin-manual/#configuring_develocity_for_unattended_configuration), export the current configuration using the Admin UI. Then adjust the exported configuration according to the [Required Changes](#required_changes) section. You can validate your unattended configuration against the schema by using the [Develocity command line tool](https://docs.gradle.com/develocity/develocityctl/1.22/) (develocityctl): ```shell develocityctl config-file validate unattended-configuration.yaml ``` If your unattended configuration is embedded in the `values.yaml` file, you can validate it with the following command: ```shell cat values.yaml | yq '.global.unattended.configuration' | develocityctl config-file validate - ``` > [!NOTE] > Unattended configuration is versioned. If an older version is provided, the application migrates the config to the latest version automatically. If you use version control, it’s recommended that you export your unattended configuration after the upgrade and store the latest version in your repository. See Migrating Unattended Configuration for details. ##### Decide on the Upgrade Command You may need to run different upgrade commands depending on your configuration changes. You can find recommendations in the [Upgrade Command Explained](#upgrade_command) section. ##### Use `dry-run` to Verify the Upgrade Before upgrading, you can use the `--dry-run` flag to verify the upgrade process. This will show you the changes that would be made without actually applying them. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ ge \ gradle-enterprise-2025.4.5.tgz \ --dry-run ``` > [!NOTE] > The actual command may differ depending on the outcome from the previous step. > [!WARNING] > If the --dry-run command completes successfully, you can proceed with the upgrade. Otherwise, review the output and make any necessary changes to your configuration. --dry-run validates syntax, verifies the chart structure, validates your configuration with schema, and checks the generated Kubernetes manifests for errors. However, it won’t detect issues like typos in optional fields or guarantee the application configuration will function correctly. ##### Execute the Upgrade Remove `--dry-run` from the command above and execute the upgrade. For example (if no changes were required): ```shell helm upgrade \ --namespace develocity \ --reuse-values \ ge \ gradle-enterprise-2025.4.5.tgz ``` ## 7. Upgrade Command Explained The `helm upgrade` command is used to upgrade an existing release. It has several flags that control how the values are used for the upgrade. Specifically, the `—-reuse-values` and `—-reset-values` flags modify the behavior around the values passed to the upgrade. * `--reuse-values`: Keeps existing values and allows the setting of additional values. * `--reset-values`: Discards any previously set values and requires all values to be set. Both flags give you fine-grained control over how values are managed during an upgrade, depending on whether you want to preserve or reset your previous configurations. For more information about the `helm upgrade` command, refer to the official [Helm documentation](https://helm.sh/docs/helm/helm_upgrade/). ### 7.1. No Changes **Use case:** You want to upgrade but keep all the values from the current deployment without any modifications. This is useful to ensure that existing values remain unchanged during an upgrade. This is the most straightforward option if no configuration needs to be modified. ```console helm upgrade \ --namespace develocity \(1) --reuse-values \(2) --version 2025.4.5 \(3) ge \(4) gradle/gradle-enterprise \(5) ``` 1. The namespace used to install Develocity 2. Reuse the configuration from the current deployment without any modifications 3. The Develocity version. If omitted, the latest version will be installed 4. The release name 5. The chart name (or archive if using a local chart) ### 7.2. Simple Changes **Use case:** You have an existing configuration and want to update the license value and disable ingress SSL, but keep the rest of the configuration. ```console helm upgrade \ --namespace develocity \(1) --reuse-values \(2) --set-file global.license.file=./develocity.license \(3) --set ingress.ssl.enabled=false \(4) --version 2025.4.5 \(5) ge \(6) gradle/gradle-enterprise \(7) ``` 1. The namespace used to install Develocity 2. Reuse the configuration from the current deployment without any modifications 3. The path to the new license file 4. Disable the Ingress SSL 5. The Develocity version. If omitted, the latest version will be installed 6. The release name 7. The chart name (or archive if using a local chart) > [!WARNING] > This method works correctly only if you add new values or override existing values. > It won’t remove any previously set values, so that you may have a corrupted configuration. Example: **previously-applied-config.yaml:** ``` objectStorage: type: s3 s3: bucket: example-bucket region: example-aws-region-1 credentials: source: environment ``` **new-config.yaml:** ``` objectStorage: type: s3 s3: bucket: example-bucket region: example-aws-region-1 credentials: type: instanceProfile ``` Upgrade command: ```console helm upgrade \ --namespace develocity \ --reuse-values \(1) --values new-config.yaml \(2) --version 2025.4.5 \ ge \ gradle/gradle-enterprise ``` 1. Reuse the configuration from the current deployment without any modifications 2. Additionally, apply the partial configuration from the new-config.yaml file We expect the `source: environment` to be removed and the `type: instanceProfile` to be added, but the result is different: ```yaml objectStorage: type: s3 s3: bucket: example-bucket region: example-aws-region-1 credentials: source: environment type: instanceProfile ``` The application throws an error since the old configuration block is no longer supported, but it’s still present. ``` UPGRADE FAILED: execution error at (gradle-enterprise/templates/enterprise-app/deployment.yaml:3:3): The `objectStorage.s3.credentials.source` attribute was removed. Please use `objectStorage.s3.credentials.type instead. ``` > [!NOTE] > The old attribute isn’t ignored during the upgrade process to quickly detect misconfigurations. ### 7.3. Complex Changes > [!WARNING] > The --reset-values flag will discard all the values from the previous configuration. Helm will use the default values defined in the chart during the upgrade, and any custom values previously set (whether through --set, --set-file, --values, or from the original release) will be ignored unless explicitly provided during the upgrade. **Use case:** You want to upgrade to Develocity 2025.4 and adjust the Object Storage configuration (see the example above). ```console helm upgrade \ --namespace develocity \(1) --reset-values \(2) --values values.yaml \(3) --set-file global.license.file=./develocity.license \(4) --version 2025.4.5 \(5) ge \(6) gradle/gradle-enterprise \(7) ``` 1. The namespace used to install Develocity 2. Discard old configuration settings 3. The path to the entire configuration file. No settings are preserved from the previous configuration 4. The path to the Develocity license file (if not included in values.yaml) 5. The Develocity version. If omitted, the latest version will be installed 6. The release name 7. The chart name (or archive if using a local chart)