You are viewing **Develocity Gradle Plugin 4.3**. To view the latest available version of the docs, see [4.4](https://docs.gradle.com/develocity/gradle/4.4/gradle-plugin/).
# Develocity Gradle Plugin User Manual
The Develocity Gradle plugin enables integration with [Develocity](https://gradle.com) and [gradle.com/scans/gradle/](https://gradle.com/scans/gradle/).
## Getting Set Up
Version 4.3.2 is the latest version and is compatible with all Gradle 5.x and later versions. See [Gradle 4.x and Earlier](#older_gradle) if you are using an earlier version of Gradle.
The instructions in this section describe applying and configuring the plugin for a single Gradle project. See [Integrating Your CI Tool](#ci_tool) for help with integrating all projects built within an environment.
### Applying the Plugin
#### Gradle 6.x and Later
The `com.gradle.develocity` plugin must be applied in the [_settings file_](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) of the build.
*
Kotlin
*
Groovy
**settings.gradle.kts:**
```
plugins {
id("com.gradle.develocity") version("4.3.2")
}
develocity {
// configuration
}
```
**settings.gradle:**
```
plugins {
id "com.gradle.develocity" version "4.3.2"
}
develocity {
// configuration
}
```
The plugin is configured via the [develocity extension](https://docs.gradle.com/downloads/gradle-plugin-javadoc/4.3.2/com/gradle/develocity/agent/gradle/DevelocityConfiguration.html) available in the settings script, which is also available via the root project in project build scripts. The same instance is used for the settings extension and root project extension.
#### Gradle 5.x
The `com.gradle.develocity` plugin must be applied to the root project of the build.
*
Kotlin
*
Groovy
**build.gradle.kts:**
```
plugins {
id("com.gradle.develocity").version("4.3.2")
}
develocity {
// configuration
}
```
**build.gradle:**
```
plugins {
id "com.gradle.develocity" version "4.3.2"
}
develocity {
// configuration
}
```
The plugin is configured via the [develocity extension](https://docs.gradle.com/downloads/gradle-plugin-javadoc/4.3.2/com/gradle/develocity/agent/gradle/DevelocityConfiguration.html) of the root project in project build scripts.
### Connecting to Develocity
To connect to a Develocity instance, you must configure the location of the Develocity server.
*
Kotlin
*
Groovy
```kotlin
develocity {
server.set("https://develocity.example.com")
}
```
```groovy
develocity {
server = "https://develocity.example.com"
}
```
#### Allowing Untrusted SSL Communication
If your Develocity server uses an SSL certificate that is not trusted by your build’s Java runtime, you will not be able to publish Build Scans without explicitly allowing untrusted servers.
To do this, set the `allowUntrustedServer` option to `true`:
*
Kotlin
*
Groovy
**Disabling SSL certificate checks:**
```
develocity {
server.set("https://develocity.example.com")
allowUntrustedServer.set(true)
}
```
**Disabling SSL certificate checks:**
```
develocity {
server = "https://develocity.example.com"
allowUntrustedServer = true
}
```
Use of this configuration is a security risk as it makes it easier for a third party to intercept your Build Scan data. It should only be used as a short term workaround until the server can be configured with a trusted certificate.
#### Authenticating
Develocity installations may be configured to require Build Scan publishing to be authenticated. Additionally, installations may be configured to only allow certain users to publish Build Scans.
> [!WARNING]
> Develocity access keys should be treated with the same secrecy as passwords. They are used to authorize access to Develocity from a build.
##### Automated Access Key Provisioning
The easiest way to configure a build environment to authenticate with Develocity is to use the `provisionDevelocityAccessKey` task.
```shell
./gradlew provisionDevelocityAccessKey
```
When executed, it opens your web browser and asks to confirm provisioning of a new access key. You will be asked to sign in to Develocity in your browser first if you are not already signed in.
When confirmed, a new access key will be generated and stored in the `develocity/keys.properties` file within the Gradle user home directory (`~/.gradle` by default).
Any existing access key for the same server will be replaced in the file, but will not be revoked at the server for use elsewhere. To revoke old access keys, sign in to Develocity and access “My settings” via the user menu at the top right of the page.
> [!NOTE]
> If your browser cannot be opened automatically at the correct page, you will be asked to manually open a link provided in the build console.
##### Manual Access Key Configuration
Access keys can also be configured manually for an environment, when automated provisioning is not suitable.
###### Creating Access Keys
To create a new access key, sign in to Develocity and access “My settings” via the user menu at the top right of the page. From there, use the “Access keys” section to generate an access key.
> [!NOTE]
> Develocity server 2025.1+ supports access key expiration.
> [!WARNING]
> After upgrading to Develocity server 2025.1+ all existing access keys will be updated to have an expiration date.
The access key value should then be copied and configured in your build environment via file, environment variable or the settings file.
###### Via File
Develocity access keys are stored inside the Gradle user home directory (`~/.gradle` by default), at `develocity/keys.properties`, in a Java properties file. The property name refers to the _host name_ of the server, and the value is the access key.
```properties
develocity.example.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq
```
The file may contain multiple entries. The first entry for a given host value will be used.
###### Via Environment Variable
The access key may also be specified via the `DEVELOCITY_ACCESS_KEY` environment variable. This is typically more suitable for CI build environments.
The environment variable value format is `«server host name»=«access key»`.
```shell
export DEVELOCITY_ACCESS_KEY=develocity.example.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq && \
./gradlew build
```
The server hostname is specified to prevent the access key being transmitted to a different server than intended. In the rare case that you require access keys for multiple servers, you can specify multiple entries separated by semicolons.
```shell
export DEVELOCITY_ACCESS_KEY=ge1.example.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq;ge2.example.com=9y4agfiubqqjea4vonghohvuyra5bnvszop4asbqee3m3sm67w5k && \
./gradlew build
```
###### Via Settings File
The `accessKey` option of the plugin allows the access key to be set via the [settings file](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html).
*
Kotlin
*
Groovy
**settings.gradle.kts:**
```
develocity {
server.set("https://develocity.example.com")
accessKey.set("7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq")
}
```
**settings.gradle:**
```
develocity {
server = "https://develocity.example.com"
accessKey = "7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq"
}
```
An access key configured for the server this way will take precedence over an access key set via the environment variable or access key file.
##### Short-Lived Access Tokens
Develocity access keys are long-lived, creating risks if they are leaked. To avoid this, users can use short-lived access tokens to authenticate with Develocity. Access tokens can be used wherever an access key would be used. Access tokens are only valid for the Develocity instance that created them.
> [!NOTE]
> Develocity server version 2024.1+ supports access tokens.
> [!WARNING]
> Changing a Develocity instance’s hostname will cause all existing access tokens to become invalid.
To create an access token:
1. Get an access key or access token for the user you want to create a token for.
2. Decide which permissions the new access token should have.
3. If project-level access control is enabled, decide which projects the new access token should be able to access.
4. Decide how long the new access token should live.
5. Make a POST request to `/api/auth/token`, optionally with the following parameters. The response will be the access token.
1. A `permissions=` query parameter with the [config values](https://docs.gradle.com/develocity/2026.1/administration/access-control/permissions-and-roles/#permissions) of each permission you want to grant. By default, all permissions for the credential used to authenticate the token request are granted to the created token.
2. If project-level access control is enabled, a `projectIds=` query parameter with the ID of each project you want to grant access to. By default, all projects for the credential used to authenticate the token request are granted to the created token.
3. An `expiresInHours=` query parameter with the token’s intended lifetime in hours, with a maximum of 24. The default is two hours, or the remaining lifetime of the credential used to authenticate the request, whichever is smaller.
The requested permissions and project ids can be specified as comma-separated lists or repeated parameters. For example, `?projectIds=a,b&projectIds=c` is valid and will request projects `a`, `b`, and `c`.
> [!NOTE]
> If project-level access control is not enabled, all access tokens will be granted the “Access all data without an associated project” permission even if it is not explicitly requested.
If the user creating the token does not have one of the requested permissions or projects, Develocity will respond with a _403 Forbidden_ error. If an access token is used to authenticate the creation request, its permissions and projects will be used for this check instead of the user’s. The request will also error if the requested lifetime would cause the new access token to expire after the one used to authenticate the request. Together, this means you cannot create an access token with more access or a later expiration than the credentials used to authenticate the request.
> [!NOTE]
> See the [Develocity API documentation](https://docs.gradle.com/develocity/2026.1/reference/develocity-api/) for more details on the `/api/auth/token` endpoint.
Here is an example using CURL to create an access token:
```shell
curl -X POST https://ge.example.com/api/auth/token?permissions=publishScan,writeCache,accessDataWithoutAssociatedProject&projectIds=project-a,project-b&expiresInHours=1 \
-H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja"
eyJraWQiOiJ0ZXN0LWtleSIsImFsZyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJpc19hbm9ueW1vdXMiOmZhbHNlLCJwZXJtaXNzaW9ucyI6WyJSRUFEX1ZFUlNJT04iLCJFWFBPUlRfREFUQSIsIkFDQ0VTU19EQVRBX1dJVEhPVVRfQVNTT0NJQVRFRF9QUk9KRUNUIl0sInByb2plY3RzIjp7ImEiOjEsImIiOjJ9LCJ1c2VyX2lkIjoic29tZS1pZCIsInVzZXJuYW1lIjoidGVzdCIsImZpcnN0X25hbWUiOiJhIiwibGFzdF9uYW1lIjoidXNlciIsImVtYWlsIjoiYkBncmFkbGUuY29tIiwic3ViIjoidGVzdCIsImV4cCI6NzIwMCwibmJmIjowLCJpYXQiOjAsImF1ZCI6ImV4YW1wbGUuZ3JhZGxlLmNvbSIsImlzcyI6ImV4YW1wbGUuZ3JhZGxlLmNvbSIsInRva2VuX3R5cGUiOiJhY2Nlc3NfdG9rZW4ifQ.H1_NEG1xuleP-WIAY_uvSmdd2o7i_-Ko3qhlo04zvCgrElJe7_F5jNuqsyDfnb5hvKlOe5UKG_7QPTgY9-3pFQ
```
The resulting token would have the following permissions:
* “Publish Build Scans”
* “Read and write Build Cache data”
* “Access all data without an associated project”
And it would have access to these projects:
* “project-a”
* “project-b”
The token would only be usable for one hour.
### Connecting to Develocity at Gradle.com
If the location of a Develocity server is not specified, Build Scans will be published to [Develocity at gradle.com](https://gradle.com/scans/gradle/). This requires agreeing the terms of service, which can be found at [https://gradle.com/legal/terms-of-use/](https://gradle.com/legal/terms-of-use/).
You can agree to the terms of service by adding the following configuration to your build.
*
Kotlin
*
Groovy
**Agreeing to the terms of service:**
```
develocity {
buildScan {
termsOfUseUrl.set("https://gradle.com/legal/terms-of-use/")
termsOfUseAgree.set("yes")
}
}
```
**Agreeing to the terms of service:**
```
develocity {
buildScan {
termsOfUseUrl = "https://gradle.com/legal/terms-of-use/"
termsOfUseAgree = "yes"
}
}
```
If you do not agree to the terms of service in your build, you will be asked interactively when trying to publish a Build Scan to [Develocity at gradle.com](https://gradle.com/scans/gradle/) each time you try to publish.
> [!WARNING]
> Be careful not to commit agreement to the terms of service into a project that may be built by others.
## Using Build Scans
### Controlling When Build Scans Are Published
Once you’ve gone through the initial setup of the previous section, you are ready to start publishing Build Scans. But when should you publish them? Every time you run a build? Only when the build fails? It’s up to you. The Develocity Gradle plugin has several options that allow you to use whatever approach works best.
#### Publishing Every Build
This is the default. There are many advantages to publishing Build Scans regularly, such as being able to track the behavior and performance of a build over time. It makes no sense relying on ad-hoc publishing of scans in such a situation as it’s easy to forget on the command line. Should you decide to explicitly enforce this default option, you can do this as follows:
*
Kotlin
*
Groovy
**Publishing a Build Scan for every build execution:**
```
develocity {
buildScan {
publishing.onlyIf { true }
}
}
```
**Publishing a Build Scan for every build execution:**
```
develocity {
buildScan {
publishing.onlyIf { true }
}
}
```
If you want to skip publishing a particular build, you can then add the `--no-scan` argument to any Gradle build.
```shell
./gradlew assemble --no-scan
```
#### Publishing On-Demand
We imagine that when you first start experimenting with Build Scans, you won’t want to publish them all the time until you become familiar with the implications. Even then, you may have good reason not to go all-in and automate the process. That’s where one-off Build Scans come in.
If you only want to publish Build Scans when explicitly requested, use the following option:
*
Kotlin
*
Groovy
**Publishing a Build Scan on-demand:**
```
develocity {
buildScan {
publishing.onlyIf { false }
}
}
```
**Publishing a Build Scan on-demand:**
```
develocity {
buildScan {
publishing.onlyIf { false }
}
}
```
You can then add the `--scan` argument to any Gradle build to publish a Build Scan.
```shell
./gradlew assemble --scan
```
> [!NOTE]
> If the build does not apply the plugin, Gradle will automatically apply the most recent version available at the time that version of Gradle was released. Gradle versions older than 8.4 do not recognize the Develocity plugin as the replacement for deprecated Gradle Enterprise and Build Scan plugins. When --scan argument is used, Gradle attempts to apply its version of the plugin which may conflict with the Develocity plugin explicitly applied to your project. If the plugin applied by Gradle wins, the new functionality provided by the Develocity plugin will not be available. This case will be highlighted using the following message: To resolve the issue, upgrade to a newer Gradle version or configure on-demand publication using one of the options described in Publishing Based on Criteria section.
You can also publish a Build Scan for the most recently run build by invoking the `buildScanPublishPrevious` task added by the plugin.
```shell
./gradlew buildScanPublishPrevious
```
Since the task name is quite long, it’s worth taking advantage of Gradle’s [abbreviated command line notation for tasks](https://docs.gradle.org/current/userguide/command_line_interface.html#sec:name_abbreviation):
```shell
./gradlew bSPP
```
#### Publishing Based on Criteria
Many of you will want a bit more control over exactly when Build Scans are published without resorting to using `--scan` each time. You may want to publish Build Scans only under the following conditions:
1. When the build fails
2. When the user running the build is authenticated with Develocity
3. If the build is running on CI
Such scenarios are covered by configuring a custom predicate.
*
Kotlin
*
Groovy
**Restricting Build Scans to failed builds:**
```
develocity {
buildScan {
publishing.onlyIf { it.buildResult.failures.isNotEmpty() }
}
}
```
**Restricting Build Scans to failed builds:**
```
develocity {
buildScan {
publishing.onlyIf { !it.buildResult.failures.empty }
}
}
```
*
Kotlin
*
Groovy
**Restricting Build Scans to authenticated users:**
```
develocity {
buildScan {
publishing.onlyIf { it.isAuthenticated }
}
}
```
**Restricting Build Scans to authenticated users:**
```
develocity {
buildScan {
publishing.onlyIf { it.authenticated }
}
}
```
*
Kotlin
*
Groovy
**Restricting Build Scans to CI builds:**
```
develocity {
buildScan {
publishing.onlyIf { !System.getenv("CI").isNullOrEmpty() }
}
}
```
**Restricting Build Scans to CI builds:**
```
develocity {
buildScan {
publishing.onlyIf { System.getenv("CI") }
}
}
```
You can use the other options in the same way. If you want to configure several things based on a set of criteria, you can use an `if` condition instead:
*
Kotlin
*
Groovy
**Encapsulating several settings based on some criteria:**
```
develocity {
buildScan {
if (!System.getenv("CI").isNullOrEmpty()) {
publishing.onlyIf { true }
tag("CI")
}
}
}
```
**Encapsulating several settings based on some criteria:**
```
develocity {
buildScan {
if (System.getenv("CI")) {
publishing.onlyIf { true }
tag "CI"
}
}
}
```
### Configuring Background Uploading
By default, Build Scans are uploaded in the background after the build has finished. This allows the build to finish sooner, but can be problematic in build environments (e.g. ephemeral CI agents) that terminate as soon as the build is finished, as the upload may be terminated before it completes. Background uploading should be disabled for such environments.
#### Disabling Programmatically
The `develocity.buildScan.uploadInBackground` property can be set to `false`.
*
Kotlin
*
Groovy
**Disabling background uploading:**
```
develocity {
buildScan {
uploadInBackground.set(false)
}
}
```
**Disabling background uploading:**
```
develocity {
buildScan {
uploadInBackground = false
}
}
```
It may be desirable to conditionally set the value based on the environment.
*
Kotlin
*
Groovy
**Conditionally set background uploading:**
```
develocity {
buildScan {
uploadInBackground.set(System.getenv("CI") == null)
}
}
```
**Conditionally set background uploading:**
```
develocity {
buildScan {
uploadInBackground = System.getenv("CI") == null
}
}
```
#### Disabling via System Property
Background uploading can be disabled by setting the `scan.uploadInBackground` system property to `false`. The system property setting always takes precedence over the programmatic setting.
The system property may be specified when invoking the build:
```shell
./gradlew build -Dscan.uploadInBackground=false
```
Or, can be set as part of the environment with the `JAVA_OPTS` or `GRADLE_OPTS` environment variables:
```shell
export GRADLE_OPTS=-Dscan.uploadInBackground=false
```
Or, can be set in the user’s `gradle.properties` file (i.e. `~/.gradle/gradle.properties`).
```properties
systemProp.scan.uploadInBackground=false
```
### Configuring Project Identifier
The documentation at the [Project-level access control](https://docs.gradle.com/develocity/2026.1/administration/access-control/project-level-access-control/) provides detailed information regarding project-level access control.
#### Setting Programmatically
The `develocity.projectId` property can be set to a necessary value.
*
Kotlin
*
Groovy
**Specifying project identifier:**
```
develocity {
projectId.set("myProject")
}
```
**Specifying project identifier:**
```
develocity {
projectId = "myProject"
}
```
#### Setting via System Property
Project identifier can be also set using the `develocity.projectId` system property. The system property setting always takes precedence over the programmatic setting.
The system property may be specified when invoking the build:
```shell
./gradlew build -Ddevelocity.projectId=myProject
```
Or, can be set as part of the environment with the `JAVA_OPTS` or `GRADLE_OPTS` environment variables:
```shell
export GRADLE_OPTS=-Ddevelocity.projectId=myProject
```
Or, can be set in the user’s `gradle.properties` file (i.e. `~/.gradle/gradle.properties`).
```properties
systemProp.develocity.projectId=myProject
```
### Capturing File Fingerprints
Build Scans capture hashes of inputs of tasks (and other units of work), to enable identifying changes to inputs when comparing builds, among other features. The overall hash value of each input property enables identifying which properties changed for a task (e.g. the source or the classpath for Java compilation). In addition, the paths and content hashes of individual input files of each property are captured by default. They allow identifying which _individual files_ changed for a task when comparing two builds.
#### When to Disable
Capturing file fingerprints increases the amount of data transmitted to the Build Scan server at the end of the build. If the network connection to the Build Scan server is poor, it may increase the time required to transmit. Additionally, it may also increase the data storage requirements for a Build Scan server. In such cases, capturing file fingerprints can be disabled.
However, if you are using Develocity and utilizing its Build Cache to accelerate your builds, it is strongly recommended to keep it enabled as identifying which files have changed between builds with build comparison is extremely effective for diagnosing unexpected Build Cache misses.
If you are using Develocity for [Predictive Test Selection](https://docs.gradle.com/develocity/2026.1/using-develocity/predictive-test-selection/) enabling capture of file fingerprints is a prerequisite.
#### How to Disable
Capture of file fingerprints can be enabled/disabled programmatically via the `buildScan` extension, or via a system property.
##### Programmatically
To enable/disable programmatically, use the `buildScan` extension added by the Develocity Gradle plugin.
*
Kotlin
*
Groovy
**Disabling file fingerprints capturing:**
```
develocity {
buildScan {
capture {
fileFingerprints.set(false)
}
}
}
```
**Disabling file fingerprints capturing:**
```
develocity {
buildScan {
capture {
fileFingerprints = false
}
}
}
```
See the [file fingerprints API reference](https://docs.gradle.com/downloads/gradle-plugin-javadoc/4.3.2/com/gradle/develocity/agent/gradle/scan/BuildScanCaptureConfiguration.html#getFileFingerprints\(\)).
##### Via System Property
To enable/disable without modifying the build script, supply a `scan.capture-file-fingerprints` system property to the build. If the property is set to `false`, capture is disabled. Otherwise, capture is enabled. The environmental setting always takes precedence over the programmatic setting.
The system property may be specified when invoking the build:
```shell
./gradlew build -Dscan.capture-file-fingerprints=false
```
Or, can be set as part of the environment with the `JAVA_OPTS` or `GRADLE_OPTS` environment variables:
```shell
export GRADLE_OPTS=-Dscan.capture-file-fingerprints=false
```
Or, can be set in the project’s `gradle.properties` file, or the user’s `gradle.properties` file (i.e. `~/.gradle/gradle.properties`).
```properties
systemProp.scan.capture-file-fingerprints=false
```
See the [Build Environment](https://docs.gradle.org/current/userguide/build_environment.html) chapter of the Gradle User Manual for more information on specifying system properties.
### Capturing Build and Test Outputs
By default, outputs generated during the build are captured and displayed in Build Scans.
Note that when disabling test output capturing, test failures will still be captured.
#### When to Disable
You may want to skip capturing build or test outputs for security/privacy reasons (i.e., some outputs may leak sensitive data), or performance/storage reasons (i.e., some tasks/tests may produce a lot of outputs that are irrelevant for your usage of Build Scans).
#### How to Disable
Output capture can be enabled/disabled programmatically via the `buildScan` extension, or via a system property.
##### Programmatically
To enable/disable programmatically, use the `buildScan` extension added by the Develocity Gradle plugin.
*
Kotlin
*
Groovy
**Disabling build or test output logging:**
```
develocity {
buildScan {
capture {
buildLogging.set(false)
testLogging.set(false)
}
}
}
```
**Disabling build or test output logging:**
```
develocity {
buildScan {
capture {
buildLogging = false
testLogging = false
}
}
}
```
See the [build logging API reference](https://docs.gradle.com/downloads/gradle-plugin-javadoc/4.3.2/com/gradle/develocity/agent/gradle/scan/BuildScanCaptureConfiguration.html#getBuildLogging\(\)) and the [test logging API reference](https://docs.gradle.com/downloads/gradle-plugin-javadoc/4.3.2/com/gradle/develocity/agent/gradle/scan/BuildScanCaptureConfiguration.html#getTestLogging\(\)).
##### Via System Property
To enable/disable without modifying the build script, supply the `scan.capture-build-logging` and/or `scan.capture-test-logging` system properties to the build. If the property is set to `false`, capture is disabled. Otherwise, capture is enabled. The environmental setting always takes precedence over the programmatic setting.
The system property may be specified when invoking the build:
```shell
./gradlew build -Dscan.capture-build-logging=false -Dscan.capture-test-logging=false
```
Or, can be set as part of the environment with the `JAVA_OPTS` or `GRADLE_OPTS` environment variables:
```shell
export GRADLE_OPTS="-Dscan.capture-build-logging=false -Dscan.capture-test-logging=false"
```
Or, can be set in the project’s `gradle.properties` file, or the user’s `gradle.properties` file (i.e. `~/.gradle/gradle.properties`).
```properties
systemProp.scan.capture-build-logging=false
systemProp.scan.capture-test-logging=false
```
See the [Build Environment](https://docs.gradle.org/current/userguide/build_environment.html) chapter of the Gradle User Manual for more information on specifying system properties.
### Capturing Resource Usage
_(plugin 3.18+)_
Build Scans capture information on key resources of the machine executing the build. This includes CPU load, memory, disk usage, network activity, and the names of the most CPU-intensive processes. This data can help analyze poor build performance, whether due to the build needing too many resources or factors external to the build. It can also help understand if the machine is underutilized and if it could do more work.
By default, resource usage is captured and displayed in Build Scans.
> [!WARNING]
> Users of Gradle’s [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html) feature must use version 7.6 of Gradle or later to benefit from resource usage capturing. When using plugin 3.18+ with earlier versions of Gradle and configuration caching turned on, resource usage capturing will be automatically disabled, and a warning message will be printed.
#### When to Disable
You may want to skip capturing resource usage for security/privacy reasons. Note that the names of processes external to the build (i.e. not the build process nor its descendants) can be [obfuscated](#obfuscating_identifying_data).
#### How to Disable
Resource usage capture can be enabled/disabled programmatically via the `buildScan` extension, or via a system property.
##### Programmatically
To enable/disable programmatically, use the `buildScan` extension added by the Develocity Gradle plugin.
*
Kotlin
*
Groovy
**Disabling resource usage capturing:**
```
develocity {
buildScan {
capture {
resourceUsage.set(false)
}
}
}
```
**Disabling resource usage capturing:**
```
develocity {
buildScan {
capture {
resourceUsage = false
}
}
}
```
See the [resource usage API reference](https://docs.gradle.com/downloads/gradle-plugin-javadoc/4.3.2/com/gradle/develocity/agent/gradle/scan/BuildScanCaptureConfiguration.html#getResourceUsage\(\)).
##### Via System Property
To enable/disable without modifying the build script, supply the `scan.capture-resource-usage` system properties to the build. If the property is set to `false`, capture is disabled. Otherwise, capture is enabled. The environmental setting always takes precedence over the programmatic setting.
The system property may be specified when invoking the build:
```shell
./gradlew build -Dscan.capture-resource-usage=false
```
Or, can be set as part of the environment with the `JAVA_OPTS` or `GRADLE_OPTS` environment variables:
```shell
export GRADLE_OPTS="-Dscan.capture-resource-usage=false"
```
Or, can be set in the project’s `gradle.properties` file, or the user’s `gradle.properties` file (i.e. `~/.gradle/gradle.properties`).
```properties
systemProp.scan.capture-resource-usage=false
```
See the [Build Environment](https://docs.gradle.org/current/userguide/build_environment.html) chapter of the Gradle User Manual for more information on specifying system properties.
### Extending Build Scans
You can easily include extra custom information in your Build Scans in the form of tags, links and values. This is a very powerful mechanism for capturing and sharing information that is important to your build and development process.
This information can be anything you like. You can tag all builds run by your continuous integration tool with a `CI` tag. You can capture the name of the environment that the build published to as a value. You can link to the source revision for the build in an online tool such as GitHub. The possibilities are endless.
You can see how the custom data appears in figures 1 and 2:
Example of a Build Scan Containing Tags and Links
Example of a Build Scan Containing Custom Values
Develocity allows listing and searching across all of the Build Scans in the system. You can find and filter Build Scans by tags and custom values, in addition to project name, outcome and other properties. In figure 3, for example, we are filtering for all Build Scans that have the tag "CI" and a git branch name of "master":
Example of a Filtered List of Build Scans in Develocity
#### Adding Tags
Tags are typically used to indicate the type or class of a build, or a key characteristic. They are prominent in the user interface and quickly inform a user about the nature of a build. A build can have zero or more tags.
They can be added at build time via the `tag()` method:
*
Kotlin
*
Groovy
**Adding tags to a build’s Build Scans:**
```
develocity {
buildScan {
tag(if (System.getenv("CI").isNullOrEmpty()) "Local" else "CI")
tag(System.getProperty("os.name"))
}
}
```
**Adding tags to a build’s Build Scans:**
```
develocity {
buildScan {
if (System.getenv("CI")) {
tag "CI"
} else {
tag "Local"
}
tag System.getProperty("os.name")
}
}
```
As demonstrated by the example above, tags are typically applied either as fixed strings within a condition or evaluated at runtime from the environment. But there are no set rules that you need to follow—these are only suggestions.
The syntax for adding a tag is:
```
tag()
```
where the is a string.
Note that the order in which you declare the tags doesn’t affect the Build Scan view. They are displayed in alphabetical order, with any all-caps labels displayed before the rest.
> [!NOTE]
> The plugin imposes the following limits on captured tags: Maximum tag count: 50 Maximum tag length: 200 characters
#### Adding Links
Builds rarely live in isolation. Where does the project source live? Is there online documentation for the project? Where can you find the project"s issue tracker? If these exist and have a URL, you can add them to the Build Scan.
They can be added at build time via the `link()` method:
*
Kotlin
*
Groovy
**Adding a VCS URL to a build’s Build Scans:**
```
develocity {
buildScan {
link("VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}")
}
}
```
**Adding a VCS URL to a build’s Build Scans:**
```
develocity {
buildScan {
link "VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}"
}
}
```
The above example demonstrates how you can attach a link to an online VCS repository that points to a specific branch provided as a system property.
The syntax for adding a link is:
```
link(