This manual covers the configuration and operation of Gradle Enterprise. It is useful for administrators and maintainers of Gradle Enterprise installations.

For installation instructions, please see one of the installation guides.

Prerequisites

This manual assumes that you have previously installed Gradle Enterprise using one of the above installation methods, and can access its web interface. If your installation is not at this point, please refer to the installation manual for your chosen installation type.

Application Configuration

Basic installation settings for Gradle Enterprise are configured via Helm values. This includes how Gradle Enterprise is accessed via the network, and how it stores its persistent data. These settings are covered in the installation manuals linked-to above.

Other configuration aspects are configured via the Gradle Enterprise application. Only users with the administration permission can do this, and they can do so by using the user menu in the top right of the application and choosing “Administration”. Until user accounts have been created, or in the case that no user accounts will be used, the system user can be used for this purpose.

Please read each of the following sections for information on recommended configuration.

System user password

The “system user” is an ever-present local user account that can be used to bootstrap the configuration of an installation, or for emergency local access in case of a failure with an external authentication provider once configured.

It is strongly recommended to immediately change the system user password from its default after installation to secure your installation.

To change the system user password, visit Gradle Enterprise in a web browser via the hostname that was specified during installation. Use the “Sign in” button at the top right of the page to sign in as the system user by using the username system and password default. You will then be required to specify a new password for the system user account. The new password should be recorded and kept secret as it can be used to access Gradle Enterprise as an administrator.

After setting the system user password, you will be redirected to the administration section.

It is recommended that the system user account not be used regularly. Instead, real administrator user accounts should be created by configuring access control.

Access control

Gradle Enterprise allows locally managed user accounts and permissions, and externally managed via an LDAP service or SAML 2.0 identity provider.

Initial setup can be performed by the system user. Subsequently, any user with the administration permission can configure access control by using the user menu in the top right of the application to access “Administration” and then “Access control”.

The following permissions are available to grant access to the described function:

Permission Description Default role name

Build Scan view

Allows viewing of Build Scans and associated build data and use of Predictive Test Selection

ge-scans-viewing

Build Scan publish

Allows publishing of Build Scans

ge-scans-publishing

Test Distribution

Allows use of Test Distribution

ge-distributed-testing

Build data export

Allows exporting build data via the API

ge-data-export

Cache Admin

Allows administration of build cache functionality

ge-cache-administration

Admin

Allows general administration of Gradle Enterprise (e.g. access control)

ge-administration

For locally managed accounts, permissions must be assigned for each user. A default set for all new users can be specified.

For externally managed user accounts (LDAP or SAML 2.0), permissions can be managed locally or by group/role membership defined by the provider. When using provider-defined membership, each permission can be mapped to one or more roles. By default, each permission maps to a unique role with the “default role name” specified in the table above. This can be changed for each permission.

Anonymous access

By default, Gradle Enterprise allows anonymous viewing and creation of Build Scans. This makes it easier to get started by reducing build configuration, but may not be suitable for your environment. Anonymous access to the built-in Build Cache node is not enabled by default.

Anonymous Build Scan viewing and publishing can be changed by going to “Administration” via the top right hand user menu, then “Access control” → “Anonymous access”.

Anonymous access to the built-in Build Cache node can be changed by going to “Build cache” via the top right hand user menu, then “Nodes” → ”View built-in node details” → “Cache access control”. See Cache access control for more information.

Authenticated Build Scan publishing

By default, Build Scan publishing does not require any build configuration as anonymous Build Scan publishing is enabled. If this is disabled, builds wanting to publish Build Scans will need to be configured with an access key of a user with permission to publish Build Scans.

Please consult the Gradle Enterprise Gradle Plugin User Manual or Gradle Enterprise Maven Extension User Manual for guidance on how to configure a build environment for authenticated Build scan publishing.

For production installations, it is recommended to disable anonymous Build Scan publishing.

Local users

Locally managed user accounts can be created to allow users to access Gradle Enterprise. They are not mutually exclusive with externally managed user accounts and both can co-exist provided the usernames and emails are unique.

Setup

  1. From the Administration page, navigate to “Access control” → “Users”

  2. Click Add.

  3. Enter details for the user and set an initial password.

  4. Assign the required roles for the user.

  5. Click Save.

SAML 2.0

A SAML 2.0 identity provider can be configured to allow users to access Gradle Enterprise using their organization credentials. User accounts for users authenticating with the SAML provider will be created on first login.

A user cannot login via a SAML provider if a locally defined account exists for the same username or email.

Sign out from Gradle Enterprise will not log users out of the SAML identity provider.

Setup

  1. From the Administration page, navigate to “Access control” → “Identity provider”

  2. Check ”Enable external identity provider”

  3. Choose “SAML 2.0” from Identity provider type options

  4. Enter a name for the identity provider

  5. Create a SAML application at your identity provider using the displayed “Service provider SSO URL” and “Service provider entity ID”.

  6. Download the metadata for the SAML application from your identity provider, and select this file for the “Identity provider metadata file” field.

  7. Configure signing/encryption options

  8. Configure attribute mapping (described below)

  9. Configure role management (described below)

  10. Click “Save”.

If any signing or encryption is being used, use “Download service provider config” to obtain a configuration file that will need to provided your identity provider.

Attribute mappings

User’s “first name”, “last name” and “email” attributes can be obtained from the identity provider or prompted for on first login.

To obtain an attribute from the identity provider, select “Manage in identity provider” for the attribute and specify the name of the SAML attribute that will provide the value. Attribute changes made at the SAML identity provider will only take affect after either a user initiated logout, administrator force logout, or session expiry.

Locally managed attributes can be updated for a user by an administrator.

Roles

User role membership can be defined by the identity provider or managed locally.

To use identity provider specified role membership, select “Defined by identity provider” in the “Role membership” section. The name of the SAML attribute that defines the roles for a user must be specified, along with the values to map to Gradle Enterprise access roles.

When using “Defined by Gradle Enterprise” as the “Role membership” option, the default roles for users can be specified. Users will be assigned the default roles when they first sign in. Changing the default roles will change the role membership of users with default roles enabled. Administrators can change role membership for individual users after they have signed in for the first time, including whether the default roles should be enabled for the user

LDAP

An LDAP identity provider can be configured to allow users to access Gradle Enterprise using their organization credentials. User accounts for users authenticating with the LDAP identity provider will be created on first login.

A user cannot login via an LDAP provider if a locally defined account exists for the same username or email.

Setup

  1. From the Administration page, navigate to “Access control” → “Identity provider”

  2. Check ”Enable external identity provider”

  3. Choose “LDAP” from Identity provider type options

  4. Complete the connection details for your LDAP provider.

  5. Configure user attributes (described below)

  6. Configure role management (described below)

  7. Click “Save”.

Attribute mappings

There are five required fields in Gradle Enterprise: “username”, ”first name”, “last name”, “email“, and “UUID”. These fields are required to be mapped to fields in your LDAP identity provider.

Commonly, the “UUID” attribute is “entryUUID”, however for LDAP providers where this is missing, another sensible unique persistent ID should be used. For Active Directory, this is usually called “objectGUID”.
Roles

User role membership can be defined by the identity provider or managed locally.

To use identity provider specified role membership, select “Defined by identity provider” in the “Role membership” section. Details on where to find roles and how they are defined must be provided.

For most LDAP providers it is common for the role object class to be “groupOfNames”, however for Active Directory this is usually “group”.

When using “Defined by Gradle Enterprise” as the “Role membership” option, the default roles for users can be specified. Users will be assigned the default roles when they first sign in. Changing the default roles will change the role membership of users with default roles enabled. Administrators can change role membership for individual users after they have signed in for the first time, including whether the default roles should be enabled for the user

Build Cache access control

When Gradle Enterprise is first installed, access to the built-in Build Cache is disabled. You will need to allow access before it can be used. See Cache access control for more information.

Build scan disk space management

Typically, disk usage is dominated by the storage of Build Scan data. How much space is used is dependent on how many Build Scans are being published and how much information is being recorded for each build. Build Scan data is stored using compression and deduplication techniques that make data growth non-linear; storing data for twice as many builds does not mean that twice the space will be required.

Gradle Enterprise provides complimentary options for removing Build Scans based on their age and automatically deleting old Build Scans when the amount of free space drops below a specified percentage. Additionally, the system can be configured to send warning emails when free space drops below a specified percentage and/or reject incoming data when free space drops below a specified percentage.

These settings can be changed by going to “Administration” via the top right hand user menu, then “Build Scans”.

A recommended configuration that maintains a predictable Build Scan retention period is:

  1. Specify a maximum Build scan age

  2. Send a warning email when there is less than 10% of space free

  3. Reject incoming data when there is less than 5% of space free

An alternative configuration that stores as much Build Scan history as space permits is:

  1. Do not specify a maximum Build scan age

  2. Automatically delete old Build Scans when there is less than 15% of space free

  3. Send a warning email when there is less than 10% of space free

  4. Reject incoming data when there is less than 5% of space free

When enabling automatic deletion of old Build Scans when disk is low, be mindful that the result of another process filling the volume that Gradle Enterprise is using will be that all Build scan data will be deleted.

If backups are created on the same volume, make sure to leave enough room for them in your thresholds. For example, if the total space that your backups take up is 40% of the disk, the above recommended settings would be 55%, 50% and 45%. It is recommended to store backups on a separate volume to simplify space management.
Configuring disk space management percentage thresholds is currently only supported when using the embedded database. Please consult your database provider for monitoring and alerts on database disk space when using a user-managed database.

Scheduled backups

For embedded database installations, the backup schedule and settings can be configured by going to “Administration” via the top right hand user menu, then “Backups”.

An administrator can be notified of the backup process outcome, which is particularly important in the case of failures. This requires administrator email details and SMTP server settings to be configured for the Gradle Enterprise instance.

See below for details on restoring backups.

Email notifications

Email server settings can be configured by going to “Administration” via the top right hand user menu, then “Email server”.

With an email server specified, Gradle Enterprise can send email notifications on completion of backups or when disk space is low. See the Build scan disk space management and Creating backups sections for more details.

Once configured, it is possible to test email configuration by running the Gradle Enterprise Admin CLI system test-notification command.

Untrusted SSL certificates

Gradle Enterprise can be configured to trust additional SSL certificates by going to “Administration” via the top right hand user menu, then “SSL trust”.

As the page notes, certificates should be added as X509 certificates in PEM format, newline seperated if there are more than one.

Additional trusted certificates can also be configured during installation using the unattended configuration mechanism, see the Untrusted SSL certificates section of the installation guide (the instructions are identical for standalone installations).

Operation

Backup and disaster recovery

Embedded database

Gradle Enterprise provides system backup and restore capabilities to facilitate disaster recovery. Backups can be triggered manually or scheduled to be done automatically on a periodic basis, and require no system downtime.

The backup process produces a single compressed archive which can be used to restore all user data to a state at the time of the backup. It is highly recommended that this archive additionally be copied to an off-host location, in the case of a complete loss of the host system or volume used to store backup archives.

In addition to disaster recovery, backup archives can be used to migrate your Gradle Enterprise data to a new host system. This can be useful in scenarios where a trial instance is promoted to a production one.

Creating backups

See Scheduled backups for details on configuring automated backups

In addition to configuring automatic scheduled backups, you may trigger a manual backup at any time by running Gradle Enterprise Admin CLI commands:

  • To create a backup, run the backup create command.

  • You can download the newly created backup locally by running the backup copy command.

The backup archive will be copied to the directory in which the command is executed. If multiple backups exist you will be prompted to select the backup you would like to copy.

Restoring from a backup

Once a backup archive is created you may use it to restore a Gradle Enterprise instance to the backup state at any time, by running the Gradle Enterprise Admin CLI backup restore command.

This command will require some downtime on Gradle Enterprise until the restore has finished.

If horizontal scaling is enabled, this command will reset the current replica count on all scalable resources to the value set in the configuration UI.

User-managed database

When data is stored in a user-managed database, backups and recovery is the responsibility of the user or database provider.

Creating backups

Please see your database provider for details on how to make backups and schedule them regularly.

Restoring from a backup
Restoring a database in-place

To restore a backup to the same database, overwriting the existing data, perform the following steps:

  1. Stop the application by running the Gradle Enterprise Admin CLI system stop command.

  2. Follow your database provider’s instructions on restoring a backup. This may be running a tool like pg_restore or restoring a database snapshot, depending on your database provider and backup type.

  3. If you are not providing superuser credentials to Gradle Enterprise, run the current database setup script used during database setup (see your installation manual) on the database and ensure that working application and migrator passwords are configured in the configuration interface or Secret resources being used.

  4. Restart Gradle Enterprise by running the Gradle Enterprise Admin CLI system start command.

Restoring to a new database instance

To restore a backup to a new database instance, perform the following steps:

  1. Stop the application by running the Gradle Enterprise Admin CLI system stop command.

  2. Follow your database provider’s instructions on restoring a backup to a new instance. This may be running a tool like pg_restore or restoring a database snapshot, depending on your database provider and backup type.

  3. Configure Gradle Enterprise with the new instance connection details and superuser credentials if those are being provided. This will mean re-running Helm, or updating the specified ConfigMap and Secret resources.

  4. If you are not providing superuser credentials to Gradle Enterprise, run the current database setup script used during database setup (see your installation manual) on the database and ensure that working application and migrator passwords are configured in the configuration interface or Secret resources being used.

  5. Restart Gradle Enterprise by running the Gradle Enterprise Admin CLI system start command.

Troubleshooting

Gradle Enterprise is unable to start

To view pod states and access logs, you will need to connect to the Kubernetes cluster Gradle Enterprise is running on. If you have a standalone installation of Gradle Enterprise, follow the instructions in standalone installation manual.

Online installations of Gradle Enterprise require connectivity to https://registry.gradle.com and https://harbor.gradle.com. The docker registry at https://registry.gradle.com is used to pull Gradle Enterprise’s images, which may be done at any time by Kubernetes. Gradle Enterprise uses https://harbor.gradle.com to verify your license and to provide automatic license updates. Both of these connections will be tried multiple times before failing, to protect against transient network errors.

Image pull failures

If Gradle Enterprise is unable to pull images from https://registry.gradle.com when a Gradle Enterprise pod is scheduled, the pod will show an ErrImagePull or ImagePullBackOff status.

The state of Gradle Enterprise’s pods may be viewed using kubectl --namespace «your-namespace» get pods.
Gradle Enterprise will be installed in the namespace used in the installation commands, which is gradle-enterprise by default. You can list the existing namespaces using kubectl get namespaces.

If the image pull failure is because of network connectivity, the pod should have events similar to:

Events:
  Type     Reason     Age                From               Message
  ----     ------     ----               ----               -------
  Normal   Pulling    5s (x4 over 97s)   kubelet            Pulling image "registry.gradle.com/gradle-enterprise/gradle-enterprise-database-migrator-image:2022.2"
  Warning  Failed     5s (x4 over 97s)   kubelet            Failed to pull image "registry.gradle.com/gradle-enterprise/gradle-enterprise-database-migrator-image:2022.2": rpc error: code = Unknown desc = failed to pull and unpack image "registry.gradle.com/gradle-enterprise/gradle-enterprise-database-migrator-image:2022.2": failed to resolve reference "registry.gradle.com/gradle-enterprise/gradle-enterprise-database-migrator-image:2022.2": failed to do request: Head "https://registry.gradle.com/v2/gradle-enterprise/gradle-enterprise-database-migrator-image/manifests/2022.2": dial tcp: lookup registry.gradle.com: no such host

If you instead see errors containing pulling from host registry.gradle.com failed with status code [manifests 2022.2.1]: 401 Unauthorized, your license is invalid.

The events of a pod can be shown by describing the pod, such by kubectl --namespace «your-namespace» describe pod «pod-name» (look for the Events section at the end).

License verification and update check failures

The below troubleshooting suggestions also apply to failing license update checks (both automatic and manually triggered).

If Gradle Enterprise fails to start because it is unable to connect to https://harbor.gradle.com then the gradle-enterprise-app-* pods will log a message similar to:

Unable to verify the license with https://harbor.gradle.com/. Gradle Enterprise must successfully verify the license with https://harbor.gradle.com/ in order to start up.
The log of a Gradle Enterprise pod can be viewed using kubectl --namespace «your-namespace» logs «pod-name».

However, if Gradle Enterprise has been able to successfully verify its license in the past three days, then it will start up successfully even if it is unable to reach https://harbor.gradle.com.

Internet connectivity from Kubernetes clusters can be affected by a number of factors - please see your cluster’s documentation for more details. Connectivity can be tested by running the following commands on a host connected to your cluster:

$ kubectl run gradle-registry-test -q --rm --attach --restart=Never \
    --image=curlimages/curl -- -sw \\n --fail-with-body --show-error \
    https://registry.gradle.com/ping
$ kubectl run gradle-harbor-test -q --rm --attach --restart=Never \
    --image=curlimages/curl -- -sw \\n --fail-with-body --show-error \
    https://harbor.gradle.com/ping

Both should return SUCCESS.

Support

If you are experiencing issues with Gradle Enterprise or related components please submit a support ticket at support.gradle.com, including details of the issue and an attached support bundle.

Support bundles assist our engineers in troubleshooting your issue by providing the following information about your Gradle Enterprise installation:

  • Server logs

  • System performance metrics

  • Gradle Enterprise database statistics

To generate a support bundle:

  • From the Administration page, navigate to “Support”.

  • Enter the system user password, and click “Generate”.

  • Download the support bundle.

It is also possible to generate a support bundle using the Gradle Enterprise Admin CLI, by executing the support-bundle command. This method should be used when the Gradle Enterprise user interface is not available.

Example downloading a support bundle using Admin CLI JAR file:

$ java -jar gradle-enterprise-admin-<VERSION>.jar \
    --kube-ns=gradle-enterprise \
    support-bundle

Example downloading a support bundle using Admin CLI Docker image:

$ docker run --rm -it \
    -v "${HOME}/.kube/config:/kube-config:ro" \
    -v "${HOME}/bundles:/home" \
    gradle/gradle-enterprise-admin-cli \
    --kube-ns=gradle-enterprise \
    support-bundle

The generated support bundle will be stored in the mounted directory (in this case it will be ${HOME}/bundles).

Generation of the support bundle may take several minutes to complete.

If you have questions about a particular Build Scan, please submit a support ticket at support.gradle.com, and attach a dump of the Build Scan.

To generate one, replace /s/ with /scan-dump/ in the Build scan url, e.g. https://dv.mycompany.com/scan-dump/vbdei7xhyojq2

Licensing

Running Gradle Enterprise requires a valid license, which is initially provided by the user as a license file during installation.

Gradle Enterprise’s current license can be viewed by going to “Administration” via the top right hand user menu, then “License” (version 2022.2.4+ only).

License expiration

Gradle Enterprise will only successfully start if it has an unexpired license (either already available or via checks during start-up). The current expiration date of your license can be checked by going to “Administration” via the top right hand user menu, then “License” (version 2022.2.4+ only).

While this version of Gradle Enterprise will not disable running instances when a license expires, there are various situations that may result in an instance restarting (e.g. Kubernetes pod adjustments and regular cycling). If the current license expires and a new license cannot be downloaded during start-up, subsequent restarts will fail.

Online updates

Online installations automatically check Gradle’s license server for license updates. It does so both on startup and every hour thereafter. If a license update requires a restart to take effect, a notification is displayed to administrators.

If license checks fail for 72 hours, the instance will fail to restart.

For online installations, all that is needed to avoid expiration is to ensure that your customer success representative has extended your license. There is no need to obtain or install a new license file, as the update will be applied automatically. If the application has failed to start due to license expiration, restart it after your customer success representative has extended your license.

In online installations, the “Administration” section “License” tab can also be used to:

  • verify the current license’s information, such as expiration date (version 2022.2.4+ only)

  • compare the current license and updated license (when an updated license has been downloaded; version 2022.2.4+ only)

  • restart Gradle Enterprise to apply the updated license (when an updated license has been downloaded; version 2022.2.4+ only)

  • check whether license checks are functioning properly (version 2022.2.5+ only)

  • initiate an on-demand license check (version 2022.2.5+ only)

license info 2022.2

Airgap updates

Airgap installations do not receive automatic license updates. If you need an updated license file, contact your customer success representative. When you receive an updated Gradle Enterprise license file, it can be applied using helm upgrade. Further details can be found in the “Changing configuration values” section of the Gradle Enterprise Upgrade Guide.

Using Gradle Enterprise

Build Scans

A Build scan is a shareable record of a build that provides insights into what happened and why.

For information on how to create Build scans, please consult the links below.

Compatibility between versions of Gradle Enterprise and the Gradle Build Scan plugin or the Gradle Enterprise Maven extension can be found here.

Build Cache

Build caching dramatically decreases build times for both local development and continuous integration builds. Build Caches store outputs from Gradle tasks and Maven goal executions and serve them to later builds to reuse, instead of the outputs being built again.

Gradle Enterprise provides a built-in Build Cache node as part of each installation, and allows optionally connecting one or more remote nodes to use as discrete caches or replicas for reducing network latency.

For information on how to use the Gradle Enterprise Build Cache, please consult the links below.

Build Cache administration is available at /cache-admin of your Gradle Enterprise installation.

Configuration

The built-in Build Cache is configured with the following defaults:

  • All cache access is disabled.

  • Target cache size of 10 GiB (how much data to retain in the cache).

  • Free space buffer size of 1 GiB (how much free disk space to ensure is available at all times, reducing cache size if necessary).

  • Maximum artifact size of 100 MiB (the largest cache artifact to accept).

  • No limit on cache entry age.

To change this configuration, click the Nodes item in the left menu to access the node listing, then click View built-in node details.

controller built in details 2022.1

If you are using an installation method that gives the built-in build cache node an exclusive data volume (like Ship), the "Target cache size" section may instead look like this:

controller exclusive volume mode 2022.1
Cache access control

By default, access to the built-in cache node is disabled. To change this, click “Add user”, and give the new user a username, password and access level of “Read” for read-only access or “Read & write” to also allow storing artifacts. The “(notes)” field is optional and can be used when there are multiple users for different scenarios.

You can also allow anonymous users to access the build cache by changing anonymous access to “Read” for read-only access, or “Read & write” to allow anonymous users to store artifacts.

When the anonymous access level is set to Read and Write, writing to the build cache does not require credentials which may allow anyone to write malicious cache entries.

When finished, click “Save” to store the required credentials and permissions.

A common arrangement is to create a user with “Read & write” access, and restrict anonymous access to “Read”. CI builds then authenticate as the user and write to the cache, while developers connect anonymously and only read from the cache.

How to configure your builds to supply credentials is described in the Gradle Build Cache User Guide for Gradle, and in the Gradle Enterprise Maven Extension User Manual for Maven.

Remote nodes

Remote build cache nodes are installed separately from Gradle Enterprise. They can be used to separate cache artifacts, distribute load, or improve build performance by having a better network link between the build and the node.

By connecting remote nodes to a Gradle Enterprise instance, you are able to configure them centrally from Gradle Enterprise, and have them replicate entries from other cache nodes.

Installation and operation of remote build cache nodes is documented in the dedicated Build Cache Node User Manual.

Connecting with Gradle Enterprise

To connect a remote node to your Gradle Enterprise installation, you first need to create a record for the node with Gradle Enterprise by following either of these options:

Manual registration

Visit /cache-admin of your Gradle Enterprise installation, and select Nodes from the left menu. In the Remote nodes > Create new node section, enter the name for your node and click Create new node.

controller after new node added 2021.2

The node will now be listed in the Existing nodes section. Each node is assigned a key and a secret. To view it, click in the View button on the Secret column for the newly created node.

controller secret 2021.2
The secret is only viewable for 5 minutes after node creation. If the node secret is lost, use the regenerate function to issue a new secret which will then be viewable for 5 minutes.

As a last step you need to update the node configuration with the assigned key and secret.

Unattended registration

In case nodes are required to be managed by provisioning software (e.g., Terraform) Gradle Enterprise offers an unattended option to register the node via the Gradle Enterprise API. Please consult the access control section of the API manual on how to connect to the Build Cache section of the Gradle Enterprise API.

Once you have access to the Gradle Enterprise API, we can start with the registration of a node via the Gradle Enterprise API.

The following example uses ge.mycompany.com as the installation host, 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja as the access key of the user which has the Cache admin role, and cURL as the HTTP client.

First, a new node (referred to as node-1) is registered in Gradle Enterprise using the Create/Update endpoint by specifying a unique descriptive value for the name of the node, e.g.:

$ curl -X PUT https://ge.mycompany.com/api/build-cache/nodes/node-1 \
    -d '{"enabled":true}' \
    -H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja" \
    -H "Content-Type: application/json"

If applicable, a replication configuration (in this example a preemptive replication from parent-node-1 is configured) can be specified at creation time:

$ curl -X PUT https://ge.mycompany.com/api/build-cache/nodes/node-1 \
    -d '{"enabled":true,"replication":{"source":"parent-node-1","preemptive":true}}' \
    -H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja" \
    -H "Content-Type: application/json"

Second, a request to the secret endpoint is made using the name of the node used in the previous step. This generates a key-secret pair that the node requires for connecting to Gradle Enterprise:

$ curl -X POST https://ge.mycompany.com/api/build-cache/nodes/node-1/secret \
  -H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja"
{
  "key":"fqysvmfd3u5dcgis5reunrxjce",
  "secret":"cpgovxdo6f6phkdyxdrfzyy43q5hflatc2umzgguxv6adap2qyyi"
}

As a last step you need to update the node configuration with the returned key and secret. Please consult the reference documentation of the Gradle Enterprise API for further functionality with regard to node management.

Update node configuration

The node must also be configured with details of the server to connect with, including the assigned key and secret. Please consult the Gradle Enterprise Registration section of the Build Cache Node User Manual for information on how to do this.

Replication

The bandwidth and latency of the network link between a build and a build cache significantly affects build performance. Replication allows users to use a cache node that they have a better network link to, while reusing artifacts from another cache node that is further away. This is particularly effective for geographically distributed teams.

The replication settings for each node can be configured via the node’s configuration page in Gradle Enterprise. They can not be configured for remote nodes via the remote node’s user interface or configuration file.

A typical arrangement is to have continuous integration builds push to a cache node on a local network, and have other nodes used by developers in different locations, ideally on their local network, use it as their replication source.

replication network simple

Replication is one-way (i.e. replication sources do not copy artifacts from nodes using them as a source). Furthermore, a node that is acting as a replication source cannot itself use a replication source.

Replication is not supported with remote nodes earlier than 3.0. This setting will not be shown for such nodes.

By default, cache entries are replicated on demand. Nodes will copy a cache entry from their replication source when that particular cache entry is requested for the first time. This avoids copying entries between nodes that will never be used, but forces builds to wait for the transfer on first use.

Preemptive replication enables better build cache performance, at the expense of more network transfer between nodes. When preemptive replication is enabled, nodes will copy cache entries from their replication source as soon as they are added. The downside of this approach is that entries may be copied that are never used. If network bandwidth usage between nodes is not a concern, this is the best configuration.

Only cache entries that are added to the replication source after the node has connected are copied preemptively. Any already existing entries will be copied on demand.

Preemptive replication is only supported for nodes of version 4.0 or later. If the node or its replication source is older than this, replication will be on demand.

Health monitoring

The Health page provides an overview of the operational status of all enabled build cache nodes.

controller health 2021.3

Each node may have a status of OK, WARN or ERROR. If all nodes are reported as OK, you can be assured that your build cache network is operating well.

WARN indicates that there is a non-critical issue, or that there is a problem that is expected to resolve itself soon. If the issue does not resolve itself, or for immediately critical issues, the ERROR status is used.

A monitoring tool friendly version of this page is available via the Monitoring page link towards the bottom of the page. This endpoint returns the statuses in plain text. If there are any ERROR statuses, the HTTP response status code for this page will be 503. Otherwise, it will be 200.

Test Distribution

Gradle Enterprise Test Distribution takes your existing test suites and distributes them across multiple compute resources to execute them faster. It requires connecting one or more test execution “agents” to Gradle Enterprise. Builds that have enabled Test Distribution connect to Gradle Enterprise, which then distributes the tests to be executed on connected agents.

Connecting builds

Please consult the Gradle Enterprise Test Distribution User Manual for information on build configuration.

Gradle Enterprise users must be granted the “Test Distribution” access control role to be able to use Test Distribution.

Builds and agents connect to the Gradle Enterprise server using a WebSocket connection. Thus, you need to ensure WebSocket support is enabled on every load balancer or proxy that is used in between the build/agent and the Gradle Enterprise server.

The “Jobs” tab provides an overview of the currently active jobs, where each row represents a running test task or goal in a Gradle or Maven build, respectively.

testdistribution jobs 2021.2

The first part of the label indicates the root project name of the build, while the second part identifies the particular task or goal. The count of assigned/desired agents shows how many agents are currently assigned to/desired by the job. More agents may be assigned as they become available. The count of compatible agents shows how many currently connected agents have capabilities that satisfy the requirements of the job.

API keys

API keys are used by agents to authorize their connection to Gradle Enterprise, and for authorizing connections to Test Distribution APIs provided by Gradle Enterprise.

API keys can be generated on the “Configuration” tab. A single API key may be used my multiple agents. Multiple can be created to facilitate a rolling update if required. Revoking an API key prevents it from being used for future registrations and API access. Connected agents will be forcibly disconnected one hour after the API key they used to connect is revoked.

testdistribution configuration 2021.2

Agents

Utilizing Test Distribution requires connecting additional compute resources, called agents, to Gradle Enterprise. The Test Distribution agent is available as a Docker image or standalone JAR and is easy to deploy and operate via Kubernetes or any modern compute platform. Please consult the Gradle Enterprise Test Distribution Agent User Manual for more on deploying and operating agents.

The “Agents” tab shows all currently connected agents.

testdistribution agents 2021.2
Auto scaling agents with pools

An agent pool is a group of agents that are to be scaled up and down based on demand. Each pool has a generated unique ID that is specified by an agent when connecting to indicate its pool, and can be used by compute platform auto scalers to determine the desired number of agents at any time for that pool.

Please refer to the Gradle Enterprise Test Distribution Agent User Manual for step-by-step instructions for auto scaling with Kubernetes.
testdistribution agent pool 2022.1
Minimum and maximum size

The minimum and maximum size of an agent pool is used to determine the desired number of agents at a given moment.

Ultimately, the actual number of agents is determined by the compute platform, which may impose incompatible limits. Where possible, ensure that the limits imposed by the compute platform are either identical to or compatible with those configured in Gradle Enterprise.

To temporarily disable a pool, set both minimum and maximum to zero.

Capabilities

Agents in a pool are expected to provide a certain set of capabilities. While an agent may provide additional capabilities, it will be rejected when connecting without at least the mandatory capabilities configured on its agent pool.

While computing the number of desired agents for a pool its capabilities are matched against the requirements of the current jobs. A pool is only utilized if it satisfies all of a job’s requirements. Therefore, you should at least add a jdk=…​ capability to each agent pool since such a requirement is added implicitly to each job. Moreover, each agent has an implicit os=…​ capability which should be added to the agent pool for the sake of consistency and in case it’s an explicit requirement of any job.

Already connected agents that don’t provide all mandatory capabilities will stay connected for up to 4 hours after adding capabilities to an agent pool. During that time they will be shown with a warning indicator on the “Agents” tab. In order to add capabilities to an existing pool, it is recommended to first add the capability to all connected agents and then edit the agent pool.

Priority

Pools with higher priority are utilized before pools with lower priority. If tests to be executed can be executed by agents from different pools, agents of the pool with the highest priority are requested. When scaling to meet demand, higher priority pools are scaled to their configured maximum before scaling lower priority pools.

You can change the priority of agent pools by dragging them on the “Configuration” tab. Pools that are higher on the list are prioritized over those below.

Deletion

Agent pools can be deleted at will when they are no longer needed. It is recommended to stop all agents in the agent pool before deleting it.

Already connected agents will stay connected for up to 4 hours after deleting an agent pool. During that time they will be shown with a warning indicator on the “Agents” tab.

Querying pool status

Agent auto scaling relies on auto scaling machinery of a compute platform regularly querying Gradle Enterprise for a pool’s desired size and starting/stopping agents to match the desired size.

The https://«hostname»/distribution/agent-pools/«pool-id» endpoint conveys a pool’s desired size at the moment, along with other information about the pool, as a JSON document.

Accessing the endpoint requires an API key via the X-API-KEY HTTP header. It can also be accessed by administrators in a browser when signed in to Gradle Enterprise.

The following demonstrates using curl to access the endpoint:

$ curl -H "X-API-KEY: «api-key»" https://«hostname»/distribution/agent-pools/«pool-id»

Which will produce output of the following form:

{
  "id": "«pool-id»",
  "name": "Linux",
  "capabilities": [
    "jdk=11",
    "os=linux"
  ],
  "minimumAgents": 1,
  "maximumAgents": 100,
  "connectedAgents": 25,
  "idleAgents": 9,
  "desiredAgents": 16
}

Auto scalers need only consider the desiredAgents field and adjust the number of running agents to match this number.

Historical usage

The “Usage” tab provides a historical overview of workload in terms of number of active jobs, agent utilization, and agent pool metrics, for the last hour, 24 hours, or 7 days.

testdistribution usage 2021.2

By default, all jobs, agents, and agent pools are shown. Adding requirement/capability criteria shows only the jobs with at least the specified requirements, only the agents with at least the specified capabilities, and only the agent pools with at least the specified capabilities.

Predictive Test Selection

Gradle Enterprise Predictive Test Selection allows developers to get faster feedback by running only tests that are likely to provide useful feedback on a particular code change using a probabilistic machine learning model. It is available for Gradle and Apache Maven™ builds.

Builds that have enabled Predictive Test Selection connect to Gradle Enterprise to select relevant tests. Gradle Enterprise users must be granted the “Build Scan view” access control role to be able to use Predictive Test Selection. For information on how to use Predictive Test Selection, please consult the Predictive Test Selection User Manual.

Appendix A: Upgrade notes

Please see upgrade notes in the Gradle Enterprise Kubernetes Helm Installation Manual for Kubernetes cluster installations or the Gradle Enterprise Helm Standalone Installation Manual for installation onto a single host.

Appendix B: Unattended configuration

Many aspects of Gradle Enterprise’s behaviour can be configured via the Admin user interface as described above.

Gradle Enterprise can optionally have this configuration set without user intervention, by specifying the configuration to Helm during installation and upgrades. This allows scripted installations or installation by configuration management tools.

In addition, the current configuration can be exported and then re-imported later, allowing rollback or restoration of configuration changes.

The configuration takes the form of a yaml file, with an optional encryption key used to encrypt secrets. The expected yaml content of file is described by a schema.

Exporting the configuration file

The easiest way to get a functional configuration yaml file is to configure Gradle Enterprise using the Admin UI, and then export the yaml file. You can download the Gradle Enterprise configuration file from a running installation by vising the Administration page, then going to Import/export and then Export.

You should then have a yaml file downloaded, and if you encrypted secrets in the file with a key, you will need to keep this key available to provide to Helm.

Writing the configuration file

The Gradle Enterprise configuration file must be well-formed yaml and conform to a specific schema. There is a brief reference of some common options later in this guide.

When editing the file you can use the latest JSON schema for code completion and validation. You can also use schemastore support on your preferred editor.

In addition, the latest Gradle Enterprise Admin CLI tool can be used to validate a the file, by running the config-file validate command.

Minimal file example

Below is a minimal example of a valid Gradle Enterprise configuration file. It must contain the configuration schema version and the hashed password of the system user.

version: 4
systemPassword: XXXXXXXXXXXXXX==

To hash the value for the system password, use the Gradle Enterprise Admin CLI config-file hash command:

$ echo "secret-password" | gradle-enterprise-admin config-file hash -o secret.txt -s -
$ cat secret.txt
JPUFnmELA2i39tDNWSdhCizAfooGr/+5Nf6syHEt73w==

If using the Docker form of the Gradle Enterprise Admin CLI, the shell alias recommended in the guide does not allow piping input as above. To make it work, omit the -t parameter from the alias, or just run the docker command directly:

$ echo "secret-password" | docker run --rm -i gradle/gradle-enterprise-admin-cli 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 is only recommended to use plain text for secrets if the values will be securely injected as part of your automation. Encrypted values will have a prefix of aes256:, as shown below.

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

Secrets that are included in the configuration file as plain text must be prefixed with “plain:”, as shown below.

email:
  authentication:
    password: plain:MySecretPassword

The Gradle Enterprise Admin CLI can be used to generate a new encryption key, and to encrypt secret configuration values using the generated key.

$ gradle-enterprise-admin config-file generate-key -o key.txt
$ echo "secret_value" | gradle-enterprise-admin config-file encrypt -k key.txt -o encrypted.txt -s -
$ cat key.txt
aes256:7l1odtTnuza0B9aa:1q2Bx/E7yz1zronpuJpOxAsgos5qpq4CtDsE2K5QnRs=
$ cat encrypted.txt
aes256:7l1odtTnuza0B9aa:VFVkWB9OBsXz79Ue:njXgHpQJIVDCkqZgUUJXl6X2eItkJndW4vT762TesaY=

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

As with hashing values, if using the Docker form of the Gradle Enterprise Admin CLI, the shell alias recommended in the guide does not allow piping input as above. To make it work, either omit the key and secret from the command and enter the values interactively:

$ gradle-enterprise-admin config-file generate-key -o -
aes256:bCy08OAN8tIbwMbW:EobFycmy1VtAGX/0motfSpVZzex3cHHf4sr6pmOrwWo=
$ gradle-enterprise-admin config-file encrypt
Enter key:
Enter secret:
aes256:bCy08OAN8tIbwMbW:XbOx4IFZ/LtMBINV:RZ4z75rcl0F94WSyIljRd/a8aw==

Or run the Docker command directly:

$ gradle-enterprise-admin config-file generate-key -o - > key.txt
$ echo "secret-password" | docker run --rm -i -v $(pwd)/key.txt:/key.txt \
    gradle/gradle-enterprise-admin-cli config-file encrypt -k /key.txt -o - -s -
aes256:bCy08OAN8tIbwMbW:XbOx4IFZ/LtMBINV:RZ4z75rcl0F94WSyIljRd/a8aw==

Configuring Gradle Enterprise to use an unattended configuration file

For details on how to configure Gradle Enterprise unattended configuration file, please see the Gradle Enterprise Kubernetes Helm Installation Manual for Kubernetes cluster installations or the Gradle Enterprise Helm Standalone Installation Manual for installation onto a single host.

How Gradle Enterprise determines the configuration it should use

Upon startup, if Gradle Enterprise has been configured with an unattended configuration file, it will store this in the database and use its configuration immediately.

Otherwise it will use a previously stored configuration set by making changes in the Administration UI, or will generate a new one based on defaults.

A given configuration file will only be used once. This means that if a configuration file has been applied, and then later changes are made through the Administration UI, the configuration file will not be reapplied unless its content changes. This ensures that changes made through the UI persist and are not overwritten.

Updating the Gradle Enterprise configuration file and restarting the system will result in its configuration being imported. Any configuration changes made via the Admin UI since the last import will be overwritten. If the file is unchanged between system restarts, any configuration changes made via the Admin UI will be preserved.

If you keep a copy of your Gradle Enterprise 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.

Appendix C: Gradle Enterprise config reference

The JSON schema describes all configuration options. Some common settings are described in more detail here.

Additionally, you can learn more about what these configuration options do by reading above, and exploring the administration page of your Gradle Enterprise instance.

Attribute Description

version

Required.

systemPassword

Required.

dailyMaintenanceTime

Every day, Gradle Enterprise runs maintenance operations on the database to keep things running smoothly. This maintenance temporarily effects Gradle Enterprise’s performance, so you should set this to a time of day (UTC) in which you anticipate low Build Scan ingest traffic.

additionalTrust

A newline-separated list of certificates which Gradle Enterprise should trust when communicating with servers using certificates not trusted by default, for example if they are signed by an internal CA.

email.administratorAddress

Some events related to Gradle Enterprise may warrant a notification to the administrators of your installation. For example, if your installation’s disk space is running low, or if a backup was created. The email.administratorAddress configuration value determines which email address such administrator notifications are sent to. Note that in order for Gradle Enterprise to send such emails, the other options under email need to be correctly filled in.

auth.anonymousRoles

Determines the permissions of users of your Gradle Enterprise instance who are not logged in. For example, you may want all Build scans to be published by authenticated developers, in which case you should not enable the buildScanPublish anonymous role. On the other hand, you may want to allow anybody to administrate build cache nodes that are connected to Gradle Enterprise, even if they aren’t logged in, in which case you should allow the cacheAdministration anonymous role.

auth.external

Configures external identity providers, using either LDAP or SAML. For example, your organization might use a Google or Microsoft product to manage permissions for all tools centrally and globally. You can configure auth.external in order to integrate Gradle Enterprise with your identity provider. This allows users to access Gradle Enterprise by clicking a button such as "Log in with SomeIdP".

backup.schedule

Can be set to one of daily, weekly or cron. The other properties to set under backup depend on which of these you choose for the schedule.

  • For a daily scheduled backup, you need to set the dailyTimeOfDay e.g. 04:00.

  • For a weekly scheduled backup, you need to set timeOfDay e.g. 04:00, and also dayOfWeek e.g. sunday.

  • For a cron scheduled backup, you need to set cronExpression to something like 0 1 * * 0, which translates to 1AM every Sunday.

advanced

You should not configure any values under advanced unless you have been directed to do so by Gradle Enterprise support.

Appendix D: Gradle Enterprise config schema downloads