---
component: ROOT
version: "2026.1"
slug: ROOT/administration/unattended-configuration
canonical_url: "https://docs.gradle.com/develocity/2026.1/administration/unattended-configuration/"
title: "Unattended Configuration"
description: "Manage Develocity configuration using declarative YAML files and Helm."
keywords: []
status: current
---

<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

# Unattended Configuration

<a id="preamble"></a>

Use unattended configuration to manage Develocity settings from a declarative YAML file.

This approach fits GitOps workflows where you version and review configuration changes.

> [!WARNING]
> When you apply unattended configuration with helm install or helm upgrade, Develocity overwrites configuration settings made manually in the UI. If you changed settings in the UI, export your configuration and update the file in version control before your next Helm deployment: Go to Administration  Import/export  Export. Update your unattended configuration (inline in values.yaml or a separate YAML file).

Develocity applies a unique unattended configuration only once, then stores it in the database. Configuration changes made with the Develocity UI persist between startups unless the configuration file is updated and applied, typically by an upgrade. When configured for unattended configuration, Develocity starts up with the configuration stored in the database.

If you keep a copy of your Develocity configuration for disaster recovery or creating test installations, you should regularly [export your configuration from your instance](#the-export-workflow), or have a policy that disallows changing settings via the UI.

<a id="prerequisites"></a>

## Prerequisites

*   Access to the Develocity UI with administrative permissions.
    
*   A Helm-based Develocity installation.
    
*   [develocityctl](https://docs.gradle.com/develocity/develocityctl/1.22/) available in your environment.
    
*   Optionally `yq` for YAML processing in the command line.
    

<a id="provide-configuration-to-helm"></a>

## Provide Configuration to Helm

You can provide unattended configuration to the Helm chart in either of these ways:

1.  Inline under `global.unattended.configuration` in _values.yaml_.
    
2.  As a separate YAML file with Helm `--set-file global.unattended.configuration=…​`.
    

If your configuration contains `aes256:` encrypted values, you must also provide the encryption key using `global.unattended.key` (in _values.yaml_ or via `--set-file`).

Administrators may use separate methods to pass the configuration and key. They may opt to provide the configuration in _values.yaml_, but pass the key separately with the `global.unattended.key` CLI option. They may also opt to provide the configuration in a separate file set with the `global.unattended.configuration` CLI option, but pass the key separately in _values.yaml_.

For end-to-end examples, see:

*   [Kubernetes chart unattended configuration](https://docs.gradle.com/develocity/2026.1/reference/helm-charts/cluster/#helm_config_unattended_configuration)
    
*   [Standalone chart unattended configuration](https://docs.gradle.com/develocity/2026.1/reference/helm-charts/standalone/#helm_config_unattended_configuration)
    

```shell
# Example: Applying a standalone configuration file
helm upgrade develocity gradle/develocity \
  --set-file global.unattended.configuration=unattended-config.yaml
```

Below is an example of a minimal, valid Develocity configuration file with only the two required properties — the configuration schema version and the hashed password of the [system user](https://docs.gradle.com/develocity/2026.1/administration/access-control/system-user/).

```yaml
version: 15
systemPassword: "«hashed-system-password»"
```

> [!TIP]
> When editing the file, use the [JSON schema](#download-the-json-schema) for code completion and validation. You can also use [SchemaStore](https://www.schemastore.org) support in your preferred editor. In addition, administrators may validate their configuration file by running the `config-file validate` command with [develocityctl](https://docs.gradle.com/develocity/develocityctl/1.22/).

<a id="handling-secrets"></a>

## Handling Secrets

To maintain security in your GitOps pipeline, protect sensitive values (for example, SMTP passwords or the system user password).

<a id="hashing-the-system-password"></a>

### Hashing the System Password

The `system` user password must be hashed before you add it to your configuration file. Use [develocityctl](https://docs.gradle.com/develocity/develocityctl/1.22/) to generate the hash:

```shell
echo "your-password" | develocityctl config-file hash -o secret.txt -s -
```

```shell
cat secret.txt
```

**Output:**

```
JPUFnmELA2i39tDNWSdhCizAfooGr/+5Nf6syHEt73w==
```

> [!NOTE]
> If using the Docker form of develocityctl, the shell alias recommended in the guide doesn’t allow piping input as above. To make it work, omit the -t parameter from the alias, or run the docker command directly:

<a id="encrypting_secret_values"></a>

### Encrypting Secret Values

The system password must be hashed, but other secrets in this file can optionally be symmetrically encrypted. It’s recommended to use only plain text for secrets if the values will be securely injected as part of your automation. Encrypted values have a prefix of `aes256:`, as shown in this configuration file snippet:

```yaml
email:
  authentication:
    password: aes256:aExYdWTRU24ZZ4Yo:wKcjYYRJajU4J4B5:Uz66aGkDDZqI2kNQ81mj4/q1oyi2Q88=
```

Secrets that are included in the configuration file as plain text must be prefixed with `plain:`:

```yaml
email:
  authentication:
    password: plain:MySecretPassword
```

[develocityctl](https://docs.gradle.com/develocity/develocityctl/1.22/) can generate a new encryption key and encrypt secret configuration values using that key:

```shell
develocityctl config-file generate-key -o key.txt
echo "secret_value" | develocityctl config-file encrypt -k key.txt -o encrypted.txt -s -
```

```shell
cat key.txt
```

**Output:**

```
aes256:7l1odtTnuza0B9aa:1q2Bx/E7yz1zronpuJpOxAsgos5qpq4CtDsE2K5QnRs=
```

```shell
cat encrypted.txt
```

**Output:**

```
aes256:7l1odtTnuza0B9aa:VFVkWB9OBsXz79Ue:njXgHpQJIVDCkqZgUUJXl6X2eItkJndW4vT762TesaY=
```

Configuration values which are applicable for encryption have the type `EncryptedSecret` in the [JSON schema](#download-the-json-schema).

> [!NOTE]
> If you encrypted secrets in the file with a key, keep this key available to provide to Helm.

<a id="develocityctl-docker-image-usage"></a>

### develocityctl Docker Image Usage

As with hashing values, if using the Docker form of `develocityctl`, the shell alias recommended in the guide doesn’t allow piping input as above. To make it work, either omit the key and secret from the command and enter the values interactively:

```shell
develocityctl config-file generate-key -o -
```

**Output:**

```
aes256:bCy08OAN8tIbwMbW:EobFycmy1VtAGX/0motfSpVZzex3cHHf4sr6pmOrwWo=
```

```shell
develocityctl config-file encrypt
```

```
Enter key:
Enter secret:
```

```
aes256:bCy08OAN8tIbwMbW:XbOx4IFZ/LtMBINV:RZ4z75rcl0F94WSyIljRd/a8aw==
```

Or run the Docker command directly:

```shell
develocityctl config-file generate-key -o - > key.txt
echo "secret-password" | docker run --rm -i -v $(pwd)/key.txt:/key.txt \
  gradle/develocityctl config-file encrypt -k /key.txt -o - -s -
```

**Output:**

```
aes256:bCy08OAN8tIbwMbW:XbOx4IFZ/LtMBINV:RZ4z75rcl0F94WSyIljRd/a8aw==
```

<a id="exporting-and-migrating"></a>

## Exporting and Migrating

The most reliable way to create a valid configuration file is to let Develocity generate it for you.

<a id="the-export-workflow"></a>

### The Export Workflow

1.  Go to **Administration**  **Import/export**  **Export**.
    
2.  Click **Export** to download your current configuration as a YAML file.
    
3.  Develocity migrates the exported file to the latest schema version supported by your instance.
    

![Exporting configuration from the UI](https://docs.gradle.com/develocity/2026.1/administration/unattended-configuration/../_images/dv-ui-export.png)

Exporting configuration from the UI

<a id="migrating-a-configuration-file-to-a-new-schema-version"></a>

### Migrating a Configuration File to a New Schema Version

When administrators want to enable a configuration setting not supported by their current version of the application, they must update the configuration file for the latest schema version. Migrating a configuration file to an updated schema version by hand is difficult. However, Develocity automatically updates every exported configuration file to the latest version of the schema.

To automatically migrate a configuration file to an updated schema:

1.  Upgrade to the newer version of Develocity with the desired configuration setting.
    
2.  Export the configuration file using the UI.
    
3.  Edit the file for the new setting.
    
4.  Apply the updated unattended configuration file using `helm upgrade`.
    
5.  Check your configuration file into source control.
    

<a id="download-the-json-schema"></a>

## Download the JSON Schema

> [!NOTE]
> Refer to the 2025.3 Administration Manual for the config schema version used in Develocity 2025.3. Older versions (prior to Develocity 2025.3) of the config schema can be found in the legacy Administration Guide.

*   [gradle-enterprise-config-schema-15.json](https://docs.gradle.com/downloads/gradle-enterprise-config-schema/gradle-enterprise-config-schema-15.json)
    
*   [gradle-enterprise-config-schema-15.json.sha256](https://docs.gradle.com/downloads/gradle-enterprise-config-schema/gradle-enterprise-config-schema-15.json.sha256)
    
*   [gradle-enterprise-config-schema-15.json.asc](https://docs.gradle.com/downloads/gradle-enterprise-config-schema/gradle-enterprise-config-schema-15.json.asc)
    
*   [gradle-enterprise-config-schema-15.json.asc.sha256](https://docs.gradle.com/downloads/gradle-enterprise-config-schema/gradle-enterprise-config-schema-15.json.asc.sha256)
    

<a id="configuration-validation"></a>

## Configuration Validation

Before you apply a new configuration to a production instance, validate the file syntax and schema version using `develocityctl`.

```shell
develocityctl config-file validate -f unattended-config.yaml
```

If your unattended configuration is embedded in _values.yaml_, you can validate only that subtree by piping it into `develocityctl`:

```shell
cat values.yaml | yq '.global.unattended.configuration' | develocityctl config-file validate -
```

<a id="reference"></a>

## Reference

For configuration keys and examples, use the canonical references:

*   [JSON schema](#download-the-json-schema)
    
*   [Kubernetes chart unattended configuration](https://docs.gradle.com/develocity/2026.1/reference/helm-charts/cluster/#helm_config_unattended_configuration)
    
*   [Standalone chart unattended configuration](https://docs.gradle.com/develocity/2026.1/reference/helm-charts/standalone/#helm_config_unattended_configuration)
    

> [!IMPORTANT]
> Before you deploy changes: Export your current settings via Administration  Import/export  Export. Apply the updated configuration using Helm. Plan for service restarts during the deployment.