Unattended Configuration

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

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

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, or have a policy that disallows changing settings via the UI.

Prerequisites

Access to the Develocity UI with administrative permissions.
A Helm-based Develocity installation.
develocityctl available in your environment.
Optionally yq for YAML processing in the command line.

Provide Configuration to Helm

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

Inline under global.unattended.configuration in values.yaml.
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:

# 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.

version: 15
systemPassword: XXXXXXXXXXXXXX==

When editing the file, use the JSON schema for code completion and validation. You can also use SchemaStore support in your preferred editor. In addition, administrators may validate their configuration file by running the config-file validate command with develocityctl.

Handling Secrets

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

Hashing the System Password

The system user password must be hashed before you add it to your configuration file. Use develocityctl to generate the hash:

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

cat secret.txt

Output

JPUFnmELA2i39tDNWSdhCizAfooGr/+5Nf6syHEt73w==

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:

echo "your-password" | docker run --rm -i gradle/develocityctl config-file hash -o - -s -

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:

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

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

email:
  authentication:
    password: plain:MySecretPassword

develocityctl can generate a new encryption key and encrypt secret configuration values using that key:

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

cat key.txt

Output

aes256:7l1odtTnuza0B9aa:1q2Bx/E7yz1zronpuJpOxAsgos5qpq4CtDsE2K5QnRs=

cat encrypted.txt

Output

aes256:7l1odtTnuza0B9aa:VFVkWB9OBsXz79Ue:njXgHpQJIVDCkqZgUUJXl6X2eItkJndW4vT762TesaY=

Configuration values which are applicable for encryption have the type EncryptedSecret in the JSON schema.

If you encrypted secrets in the file with a key, keep this key available to provide to Helm.

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:

develocityctl config-file generate-key -o -

Output

aes256:bCy08OAN8tIbwMbW:EobFycmy1VtAGX/0motfSpVZzex3cHHf4sr6pmOrwWo=

develocityctl config-file encrypt

Enter key:
Enter secret:

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

Or run the Docker command directly:

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==

Exporting and Migrating

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

The Export Workflow

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

Exporting configuration from the UI

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:

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

Download the JSON Schema

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.

Configuration Validation

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

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:

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

Reference

For configuration keys and examples, use the canonical references:

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.