Develocity Administration Manual

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

Prerequisites

This manual assumes that you have previously installed Develocity using one of the above installation methods, and can access its web interface. If your installation isn’t at this point, refer to the installation manual for your chosen installation type.

Application Configuration

Basic installation settings for Develocity are configured with the Helm values.yaml file. This includes how Develocity is accessed via the network and how it stores its persistent data. Configuration settings related to installation are described in the installation manuals. Additional Helm configurations are documented in the following manuals:

Other configuration aspects are configured via the Develocity 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.

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 a configured external authentication provider. The system user is hard-coded to have the Administer Develocity and Generate support bundles permissions (see Access control).

The system user has a username of system and a default password that’s randomly generated for new installations.

 The system user password can also be set in an unattended configuration. If unattended configuration was used when installing Develocity, sign in with the password specified in the configuration instead of using the commands below.

The first time a user logs in as the system user using the default password, they will be prompted to change the password. Record the new password and keep it secret since it can be used to access Develocity as an administrator. It’s recommended that the system user account not be used regularly. Instead, create administrator user accounts and assign them the Administrator role. These accounts can also update the system user account password.

To sign in as the system user:

Get the default password using develocityctl

develocityctl has a command to get the default system password: system get-default-system-password.

Set the password using develocityctl

In addition to the get-default-system-password command, develocityctl also has a command that sets the system password to a value you provide: system reset-system-password

This can be used as an alternative to looking up the default system password, and avoids choosing a new password after the first login. The new password should be recorded and kept secret as it can be used to access Develocity as an administrator.

Get the default password using kubectl

If you have kubectl installed and configured, you can view the default system password using the following command:

kubectl -n develocity get secret gradle-default-system-password-secret --template={{.data.password}} | base64 --decode
 If you installed Develocity in a namespace other than develocity, adjust the command accordingly.

Find the default password in the app logs

The gradle-enterprise-app-* pods log the system password on startup when the default system password is used. It can be found by searching for Using default system password:.

While kubectl logs can be used to get the app logs, it doesn’t have an option to get the beginning of the log, only the end. As such, this method won’t be of much use except with an external log aggregator or viewer.

Access control

Develocity 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 “Administer Develocity” 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 table describes Develocity permissions and lists the corresponding configuration file values:

Permission

Config value

Description

View Build Scans and build data

viewScan

Allows viewing of Build Scans and associated build data

Publish Build Scans

publishScan

Allows publishing of Build Scans

Access build data via the API

exportData

Allows access to the Develocity API

Use Test Distribution

testDistribution

Allows use of Test Distribution

Use Predictive Test Selection

predictiveTestSelection

Allows use of Predictive Test Selection

Read Build Cache data

readCache

Allows reading of Build Cache data

Read and write Build Cache data

writeCache

Allows reading and writing of Build Cache data

Read Build Cache data and write Bazel CAS data

readCacheWriteCas

Allows reading of Build Cache data and writing data to the content-addressable storage exposed by the Build Cache’s Bazel functionality. If you typically assign read-only access to the cache for developers and write access only for the CI, consider assigning developers using Bazel this permission instead. The readCacheWriteCas permission allows developers using Bazel to benefit from richer local Build Scans while maintaining a similar level of security.

Access all data without an associated project

accessDataWithoutAssociatedProject

Allows users to access and push data that’s not associated with a project

Access all data with or without associated project

accessAllDataWithOrWithoutAssociatedProject

Allow users to access and push all data for all projects, and data that’s not associated with a project.

Configure Build Caches

administerCache

Allows configuration of Build Cache functionality

Configure projects

administerProjects

Allows configuration of projects and project groups for project-level access control from the Administration console, or by using the Develocity API.

Generate support bundles

generateSupportBundle

Allows the generation of support bundles

Administer Develocity

administerApp

Allows general administration of Develocity (for example, access control).
“Administer Develocity” doesn’t imply the “Configure Build Caches” or “Configure projects” permissions.
The “Access all data without an associated project” and “Access all data with or without associated project” permissions are granted to all users automatically when project-level access control is disabled.

Users' permissions are managed via assigning roles to them, either in Develocity or by mapping an external Identity Provider’s roles. Both methods are described later in this section.

Develocity includes a basic set of roles pre-configured, which are shown in the table below. They should be enough for many use-cases. Custom roles can be created and managed by going to Administration via the top right hand user menu, then Access control  Roles, or by using unattended configuration.

Role

Display name

Description

Permissions

admin

Administrator

Administer Develocity

Configure Build Caches
Configure projects
Generate support bundles
Administer Develocity

api-client

API Client

Access build data via the API. Doesn’t include access to the administrative API endpoints.

Access build data via the API

ci-agent

CI Agent

Use Develocity for CI builds

Publish Build Scans
Use Test Distribution
Use Predictive Test Selection
Read Build Cache data
Read and write Build Cache data
Access all data without an associated project
Access all data with or without associated project

developer

Developer

Use Develocity

View Build Scans and build data
Publish Build Scans
Use Test Distribution
Use Predictive Test Selection
Read Build Cache data
Read Build Cache data and write Bazel CAS data

For externally managed user accounts (LDAP or SAML 2.0), roles can be managed locally or by group/role membership defined by the provider. When using provider-defined membership, each Develocity role can be mapped to one external group/role.

 Changes to access control settings may take up to 20 minutes to propagate through the various components of Develocity.

Anonymous access

By default, Develocity 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 isn’t enabled by default.

Permissions for anonymous users can be changed by going to Administration via the top right hand user menu, then Access control  Anonymous access.

 Changes to access control settings may take up to 20 minutes to propagate through the various components of Develocity.

Authenticated build access

Builds can authenticate with Develocity by supplying an “access key”.

Consult the Develocity Gradle Plugin User Manual or Develocity Maven Extension User Manual for guidance on how to configure builds to authenticate with Develocity.

Local users

Locally managed user accounts can be created to allow users to access Develocity. They’re 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 User.

  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 Develocity using their organization credentials. User accounts for users authenticating with the SAML provider will be created on first login. A user can’t log in via a SAML provider if a locally defined account exists for the same username or email.

Signing out from Develocity doesn’t 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. (Optional)
    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.

  8. Configure Attribute mappings.

  9. Configure Roles membership.

  10. Click Save.

Attribute mappings

User’s “given name”, “surname” 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.

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

LDAP

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

A user can’t log in 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