Develocity Administration Manual

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 effect after either a user initiated logout, administrator force logout, or session expiry.

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

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 Develocity access roles.

When using “Defined by Develocity” 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.

By default, SCIM support is disabled. To enable it:

Specific instructions for the following SCIM-capable systems are available:

This section assumes you have a pre-existing application for Develocity in Azure Active Directory, and the application is already configured for SAML single sign on. If not, configure an application before proceeding.

For more information, refer to the Azure Active Directory documentation:

This section assumes you have a pre-existing app integration for Develocity in Okta, and the app integration is already configured for SAML 2.0 single sign on. If not, configure an app integration before proceeding.

For more information, refer to the Okta documentation:

To configure access to a project in Develocity, it first has to be created.

You need to create and assign projects in Develocity before using them in your builds.

To manage projects:

In the Projects section you can:

To associate projects to users, Project Groups are used. Project groups are to projects as roles are to permissions - each group contains a set of projects, and when assigned to a user, will give the user access to all of its projects.

In the “Project Groups” section you can:

The display name, description, the identify mapping provider, and the projects the group contains can all be edited.

Assigning project groups to users is done when editing a user, identically to how roles are assigned. Like roles, project groups can also be mapped from an external identity provider or specified in the Modify project group dialog in Develocity.

The “Access all data without an associated project” and “Access all data with or without associated project” permissions can be used to circumvent some level of per-project access control, as described in the access control section. Frequently using these permissions reduces the usefulness of project-level access control. However, they may be useful for bot accounts or CI agents, or to maintain visibility of past data that does not have an associated project.

For project-level access control to be useful, builds must self-identify as a project. Otherwise, they will be accessible by all users with the “Access all data without an associated project” permission. For information on how to configure a project ID, please consult the links below.

By default, project-level access control is disabled and Develocity does not enforce project-level access for builds associated with a project. You can configure project access before enabling project-level access control.

To enable project-level access control:

Project-level access control will take effect once the configuration is applied.

Once you enable project-level access control, the “Allow data without an associated project” checkbox appears. The “Allow data without an associated project” setting controls whether data without an associated project can be submitted to Develocity. It is enabled by default, and we recommend keeping it that way at least until all of your builds specify a project ID.

Access tokens are signed JWTs, or JSON Web Tokens, and work like OAuth and OIDC access tokens. There is no central directory of access tokens that manages their validity. Access token validity is based on their signature and associated signing key. However, there are some situations, such as a token leak, where you may need to invalidate tokens. You can use the POST /api/auth/revoke-signing-keys endpoint to revoke all existing access tokens.

Using this endpoint requires the “Administer Develocity” permission. It will delete any existing access token signing keys, and create a new one. This will invalidate all existing access tokens. This may take a few minutes to complete. It does not affect access keys.

The signing keys used for access tokens are stored in Develocity’s database. They are automatically rotated every seven days. This will not cause any interruptions in authentication.

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

When storing scans in the database, an alternative configuration that stores as much Build Scan history as space permits is:

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

Once object storage is configured in your Helm chart, perform the following steps to store incoming Build Scan data in the store:

If you are using EKS service account credentials, ensure that you have configured Helm with the necessary service account annotation and redeployed.

Once Develocity has restarted, all new Build Scans will be stored in the configured object store. Any existing Build Scan will be loaded from the database, and will eventually be evicted according to the configured age-based retention period. If one of your reasons for adopting object storage was to reduce the size of your database, note that you will only start to see the size of your database reducing once Build Scan data starts aging out after the retention window. To reduce the size of the database, Build Scan data needs to be deleted, and the space it took up needs to be reclaimed - a process which happens regularly, both daily and weekly.

The backup location is currently configured separately during installation. For standalone installations please see the Develocity Helm Standalone Installation Manual. For Kubernetes installations please see the Develocity Helm Kubernetes Installation Manual.

See below for details on restoring backups.

See Scheduled backups for details on configuring automated backups.

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

To create a backup, run the following command:

The Admin CLI responds to a successful command with the following:

The output includes the name of the backup, which can be found in the /opt/gradle/backups directory. 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.

Once a backup archive is created you may use it to restore a Develocity instance to the backup state at any time.

To restore the database from a backup, run the following command:

The Admin CLI responds to a successful command with the following:

This command requires some downtime on Develocity until the restore is finished. See the Develocity Admin CLI User Manual for more information.

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

By default, access to the Build Cache is disabled. There are two access control mechanisms that can be used. Which one you should use depends on the version of the Develocity Gradle plugin or Develocity Maven extension you will be using.

Version 3.11+ of the Develocity Gradle plugin and version 1.15+ of the Develocity Maven extension can authenticate to the build cache with Develocity access keys. Permissions for these users are managed via the same access control mechanism used for other functions. Users with the “Build cache read” permission can read data from any connected build cache, while users with the “Build cache write” permission can read and write data from any connected build cache.

To control access for earlier versions, separate username and password credentials can be specified in the “Build Cache” section of Develocity, in the details section for each build cache node. This section of Develocity is only accessible by users with the "Build cache admin" permission.

How to configure your builds to supply credentials is described in the Develocity Gradle Plugin User Manual for Gradle, and in the Develocity Maven Extension User Manual for Maven.

Anonymous access control can also be configured using the same anonymous access control mechanism used for other functions, or by configuring node-specific anonymous permissions in the details section for each build cache node. When both are configured, the most permissive setting is used.

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

A simple arrangement is to have continuous integration builds push to a geographically co-located build cache, and have other build cache nodes used by developers in different locations, ideally on their local network, replicating from it.

More advanced geographically-distributed deployments are supported to improve the speed of builds writing to the cache and enhance network resiliency.

Build cache nodes can be utilized as near-caches, providing build agents with fast writes and low latency reads for the most frequently accessed cache artifacts at the locations the nodes are deployed. Cache artifacts stored to a build cache node are copied to the Develocity server, which maintains a centralized cache catalog for the build cache network. Less frequently accessed cache entries are then copied to build cache nodes on demand from Develocity server unless the node has preemptive mode enabled.

For this type of deployment, it is recommended that the Develocity build cache storage is sized to be at least twice that of the largest build cache node cache size in the network. See the build cache storage section for information on how to size Develocity build cache storage.

To enhance fault-tolerance, multiple build cache nodes can be deployed at a location and added to the same DNS-based load balancer group to act as a build cache node cluster.

Agents in a pool can 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.

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

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

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. Any agent in the pool that has capabilities that do not exactly match the ones of the poll is shown with a warning indicator on the Agents tab.

In order to add a new capability to an existing pool, it is recommended to first add the capability to all connected agents and then edit the agent pool. This way agents connecting will not be rejected while the change is being applied (e.g. due to a rolling update).

In order to remove a capability from an agent pool, we recommend to first remove the capability from the pool before removing it from connected agents. Agents in the pool that still provide the capability will no longer match the corresponding build requirement and not be assigned.

If project-level access control is enabled, usage of an agent pool can be restricted to specific project groups. In that case, only builds for projects in the specified groups can run tests on agents in this pool for users with access to those projects.

Agents from unrestricted pools can be used by any project. This is useful when Test Distribution agents provide access to secured resources, such as databases or other services, that should not be accessible to all projects. To prevent misconfiguration, such agent pools require using pool-specific registration keys for authentication.

Registration keys are a pool-specific means to authorize agents with Develocity and the pool they are connecting to. They can be generated by editing an agent pool on the Configuration tab.

A single registration key may be used my multiple agents in the same pool, but not by an agent in another pool. Multiple registration keys can be created to facilitate a rolling update if required. Revoking a registration key prevents it from being used for future registrations. Connected agents will be forcibly disconnected one hour after the registration key they used to connect is revoked.

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.

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.

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

The https://«hostname»/api/test-distribution/agent-pools/«pool-id»/status 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 access key provided via an Authorization: Bearer «access-key» HTTP header, with the user having the Test Distribution permission. It can also be accessed in a browser when signed in to Develocity and having the Test Distribution permission.

To create an access key, log into Develocity and go to https://«hostname»/settings/access-keys and click on the Generate button.

The following demonstrates using curl to access the endpoint:

Which will produce output of the following form:

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

See the Authenticating with Develocity section of the Develocity Maven Extension User Manual for details.

See the Authenticating section of the Develocity Bazel Configuration Guide for details.