Develocity npm Agent User Manual (beta) | Develocity Documentation

Getting set up

Setup

Install the agent

The Develocity npm agent is an npm package, but it is not publicly available on the npm registry. To install it in your project, you can use the command line below.

npm install --save-dev https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-0.10.0.tgz

npm support needs to be enabled in your license to use the Develocity npm agent. Reach out to us to enable npm support.

The agent is a regular Node.js module. In order for it to instrument npm invocations, it needs to be preloaded, using the -r option of Node.js. In order for this flag to be passed to the npm process, it needs to be set in the NODE_OPTIONS environment variable.

While using this mechanism to load the agent directly is possible, it requires the NODE_OPTIONS environment variable to be set and unset manually depending on the availability of the agent in the project (or in the system at large for that matter, since NODE_OPTIONS applies to any Node.js process).

As this can be tedious, error-prone, and lead to unexpected failures, we recommend using the agent loader to set NODE_OPTIONS once and never have to worry about it again.

Recommended: using the agent loader

The agent loader is a small package whose sole purpose is to load the agent if it’s currently available in the project, or silently ignore if it’s not.

To install it, use the command line below.

npm install --global https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-loader-0.9.0.tgz

To ensure that the agent is preloaded, set the NODE_OPTIONS environment variable as follows:

export NODE_OPTIONS='-r $(npm root -g)/@gradle/develocity-agent-loader'

From now on, the agent will be automatically preloaded if it has been installed for the current project.

By default, the agent loader will simply ignore any error in loading the agent (which usually simply means that the agent itself is not installed for the current project). If you expect the agent to be loaded, but it’s not, you can set the DEVELOCITY_AGENT_LOADER_DEBUG environment to true to make the loader print the error.

Alternatively: managing `NODE_OPTIONS` manually

There are situations, such as CI, where managing NODE_OPTIONS manually is just as convenient as depending on the agent loader as a global package. In these cases, or if for other reasons you cannot use the agent loader, you can load the agent directly.

To ensure that the agent is preloaded, use the NODE_OPTIONS environment variable as such:

export NODE_OPTIONS='-r @gradle/develocity-agent/preload'

Note that the agent will be preloaded for all invocations of Node.js. This can be inconvenient when working on local development environments, as NODE_OPTIONS needs to be set and unset depending on the availability of the agent in the project to avoid invocations of Node.js to fail. If you are in a situation where using the agent loader is unfeasible and need to manage NODE_OPTIONS manually, you might want to consider tooling to do that for you, such as dotenvx or direnv.

Configuration

To configure the agent, create a file called develocity.config.js or develocity.config.cjs in the root of your project.

module.exports = {
  server: {
    url: 'https://develocity.mycompany.com',
  },
}

Configuration files using ESM or TypeScript are not supported.

This is the minimum configuration required to publish a Build Scan. Publishing a Build Scan to scans.gradle.com is not supported.

Alternatively, you can use environment variables to configure the agent. Use DEVELOCITY_URL to set the Develocity server URL:

export DEVELOCITY_URL=https://develocity.mycompany.com

Authenticating with Develocity

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.

Develocity access keys should be treated with the same secrecy as passwords. They are used to authorize access to Develocity from a build.

Access key configuration

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.

Develocity server 2025.1+ supports access key expiration.

After upgrading to Develocity server 2025.1+ all existing access keys will be updated to have an expiration date.

Configuring access keys

Using the configuration file

The access key may be specified through the server.accessKey property in the configuration file.

Set server.accessKey to a function that takes the hostname of the Develocity server and returns a string with the access key to use when connecting to that server, or undefined if there’s no suitable access key available for the provided host. If you use a properties file and/or want to retrieve the access keys from the exact location as the Develocity Gradle plugin, consider using a helper.

Example: retrieve the access keys from the same location as the Develocity Gradle plugin

const { fromPropertiesFile, inGradleUserHome } = require('@gradle/develocity-agent/api/config');

module.exports = {
  server: {
    url: 'https://develocity.mycompany.com',
    accessKey: fromPropertiesFile(inGradleUserHome()),
  },
}

Example: retrieve the access keys from a properties file in a known location

const { fromPropertiesFile } = require('@gradle/develocity-agent/api/config');
const { resolve } = require('node:path');
const { homedir } = require('os');

module.exports = {
  server: {
    url: 'https://develocity.mycompany.com',
    accessKey: fromPropertiesFile(() => {
      return resolve(homedir(), '.develocity-keys.properties');
    }),
  },
}

Example: retrieve the access keys from a JSON file in a known location

const { resolve } = require('node:path');
const { homedir } = require('os');

module.exports = {
  server: {
    url: 'https://develocity.mycompany.com',
    accessKey: (url) => {
        const keys = require(resolve(homedir(), '.develocity-keys.json'));
        return keys[url];
    },
  },
}

Using environment variables

The access key may be specified via the DEVELOCITY_ACCESS_KEY environment variable.

The environment variable value format is «server host name»=«access key».

$ export DEVELOCITY_ACCESS_KEY=develocity.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq && \
  npm test

The server host name is specified in order 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.

$ export DEVELOCITY_ACCESS_KEY=develocity1.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq;develocity2.mycompany.com=9y4agfiubqqjea4vonghohvuyra5bnvszop4asbqee3m3sm67w5k && \
  npm test

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.

Develocity server version 2024.1+ supports access tokens.

Changing a Develocity instance’s hostname will cause all existing access tokens to become invalid.

To create an access token:

Get an access key or access token for the user you wish to create a token for.
Decide which permissions the new access token should have.
If project-level access control is enabled, decide which projects the new access token should be able to access.
Decide how long the new access token should live.
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 of each permission you wish 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 wish 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-seperated lists or repeated parameters. For example, ?projectIds=a,b&projectIds=c is valid and will request projects a, b, and c.

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.

See the API documentation for more details on the /api/auth/token endpoint.

Here is an example using CURL to create an access token:

$ curl -X POST https://ge.mycompany.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.

Capturing Build Scans when running npm through Gradle

(npm agent 0.10.0+, Gradle Develocity Plugin 4.0+)

The Gradle Develocity plugin exposes a convenience API for producing Build Scans when running npm through a Gradle task.

To use it, set up your npm project as if it were not running through Gradle, following the setup instructions.

Then, use the develocity.integrations API to inject the relevant Gradle environment into the task running npm:

tasks.register<Exec>("npmTest") { // Replace with your own npm task

    val npmAgentEnvironment = develocity.integration.npm.environment.get()
    environment.putAll(npmAgentEnvironment)

    commandLine("npm", "run", "test")
}

The environment will contain at least the following values:

NODE_OPTIONS, with the value "-r @gradle/develocity-agent/preload".
GRADLE_USER_HOME, with the value of the Gradle user home as seen by that invocation of the Gradle Build Tool. For more information, see the Gradle documentation.

The environment may contain more variables, used for internal purposes. Variables other than the ones listed above should are subject to change, and should not be depended on.

Each npm invocation instrumented this way will generate its own Build Scan. In complex projects, with complex workflows comprising many npm invocations managed by Gradle, this can result a large number of npm Build Scans per Gradle run. If this results in what you believe is unnecessary noise, consider only using this feature on tasks that you deem relevant.

Using Build Scans

Build Scans are a record of what happened during a build, captured and visualized by Develocity.

Build Scans are an important tool for developing and maintaining npm projects. They provide insights into exactly what your builds are doing, helping you identify problems with the build environment, performance, and more. They can also help you understand and improve the build more generally, and make collaborating with others easier.

Figure 1. Build Scans can be published to Develocity

Configuring project identifier

The documentation at the Project-level access control provides detailed information regarding project-level access control.

Versions before 0.9.1 of this agent do not allow specifying project identifier

Use projectId configuration key to specify the project identifier:

module.exports = {
  projectId: 'myProject',
}

Alternatively, use DEVELOCITY_PROJECT_ID environment variable to specify the project identifier:

Add the DEVELOCITY_PROJECT_ID environment variable

export DEVELOCITY_PROJECT_ID=myProject

Capturing scripts output

All the output generated during the npm invocation is captured and displayed in Build Scans.

Extending Build Scans

You can include extra custom information in your Build Scans through tags, links, and values. This is a powerful mechanism for capturing and sharing information 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 the following figures:

Figure 2. A Build Scan containing tags and links

Develocity allows listing and searching across all 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 the following figure, for example, we are filtering for all npm Build Scans that have the tag "CI" and a git branch name of "release":

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

To add a tag, use the buildScan.tags configuration key.

module.exports = {
  buildScan: {
    tags: ['CI'],
  },
}

Alternatively, add an environment variable prefixed with DEVELOCITY_TAG_ and assign the string true to it.

Add the DEVELOCITY_TAG_<tag> environment variable

export DEVELOCITY_TAG_CI=true

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.

You can see the effect of a custom tag in figure 2.

The Develocity npm agent imposes 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.

Use the buildScan.links configuration key to add a link. The value is an object where the keys are the link labels and the values are the URLs. Each link URL must be a valid URL with a scheme of http, https, or mailto.

module.exports = {
  buildScan: {
    links: {
      VCS: 'https://github.com/myorg/my-super-project/tree/my-new-feature',
    },
  },
}

Alternatively, add an environment variable prefixed with DEVELOCITY_LINK_. What comes after the prefix will be the name associated with the link, while the value of the environment variable will determine the URL it points to.

Add the DEVELOCITY_LINK_<name>=<URL> environment variable

export DEVELOCITY_LINK_VCS=https://github.com/myorg/my-super-project/tree/my-new-feature

The <name> is a string identifier that you choose, and that means something to you.

You can see the effect of a custom link in figure 2, which shows how a label for a given VCS (here GitHub) becomes a hyperlink that anyone viewing the Build Scan can follow.

The Develocity npm agent imposes limits on captured links:

The link must use the http, https, or mailto scheme
Maximum link count: 20
Maximum link label length: 100 characters
Maximum link URL length: 100,000 characters

Adding custom values

Some information just isn’t useful without context. What does "1G" mean? You might guess that it represents 1 gigabyte, but of what? It’s only when you attach the label "Max_heap_size_for_build" that it makes sense. The same applies to git commit IDs, for example, which could be interpreted as some other checksum without a suitable label.

Custom values are designed for these cases that require context. They’re standard key-value pairs, in which the key is a string label of your choosing and the values are also strings, often evaluated from the build environment.

To add a custom value, use the buildScan.values configuration key.

module.exports = {
  buildScan: {
    values: {
      'CI Build Type': 'QA Build',
    },
  },
}

Alternatively, add an environment variable prefixed with DEVELOCITY_VALUE_. What comes after the prefix will be the key, while the value of the environment variable will determine what the custom value is.

Add the DEVELOCITY_VALUE_<name>=<value> environment variable

export DEVELOCITY_VALUE_CIBuildType=QA_Build

As with tags, you can filter Build Scans by custom values in Develocity.

The Develocity npm agent imposes limits on captured custom values:

maximum custom value count: 1,000
maximum custom value key length: 1,000 characters
maximum custom value value length: 100,000 characters

Viewing test results

The Develocity agent will capture test execution results and publish them to the Develocity server. After your Build Scan® is ready, you can view and analyze the results.

The following test frameworks are supported by the Develocity agent:

Test framework	Compatible versions	Develocity npm agent version
Jest	≥ 28.1	≥ 0.10.0

Test framework

Compatible versions

Develocity npm agent version

Jest

≥ 28.1

≥ 0.10.0

Contact us at support.gradle.com if the results are not correctly displayed or if you require support for a different test framework.

Configuring test execution results capturing

To enable test execution results capturing an additional, framework-specific configuration may be required.

Jest

To enable test execution results capturing for Jest, the Develocity Jest reporter has to be configured in the Jest configuration:

jest.config.js

/** @type {import('jest').Config} */
const config = {
    reporters: [
        'default',
        '@gradle/develocity-agent/jest-reporter',
    ],
};
module.exports = config;

Test overview page

The Test overview page shows a high-level overview of all the tests that were executed as part of the build. The test results are displayed hierarchically: they are grouped by process, test file and finally test case. Next to each process, test file and test case, the outcome and the total time are displayed.

Test outcomes

Every process, test file and test case has an outcome. For a process, the outcome is either SUCCESS, indicating that the process was successful, FLAKY, which means that at least one test file was flaky, or FAILED, if a test file has failed.

For test files, the outcome can be SUCCESS, meaning that all executed test cases were successful, FAILED, indicating that at least one test case failed, FLAKY, meaning that at least one test case was successful only after retry, or SKIPPED, meaning that the test file was not executed.

For tests cases, the outcome can be SKIPPED, meaning that the test case was not executed, SUCCESS, meaning that the test case was successful, FAILED indicating that the test case was failed, or FLAKY, meaning that the test case was successful only after retry.

Test timings

On a process, the total time corresponds to the total amount of wall-clock time the process took to execute.

On a test file, the total time corresponds to the total amount of wall-clock time the test file took to execute.

On a test case, the total time corresponds to the total amount of wall-clock time the test case took to execute.

Clicking on a test file will open the details for this test file, which will display the results of the test cases which ran as part of this test file.

Test file details page

The Test file details page displays the results of the test cases which ran as part of the selected test file.

Errors that may have happened during the setup or cleanup phase of the test file execution are reported in this page.

Some frameworks, such as Jest, may report in this page errors that occur not only during the setup or cleanup of a test file but also during the execution of test cases.

The file’s overall outcome is broken down into Test file setup/cleanup and Test execution outcomes. Test file setup/cleanup tracks whether a failure occurred in the file’s setup / teardown callbacks, and Test execution whether it was a test case that caused the test file to fail.

At the bottom of the page, the test cases that were executed as part of this test file are listed, along with the time and outcome of each execution. A test case may be run more than once in case of retries.

Clicking on a test case will open the details for this test case, which will display the results of the executions of this test case.

Test case details page

The Test case details page displays the results of the executions of the selected test case.

The total time and outcome of each execution of the selected test case are displayed on the page. If an execution failed with an exception, then the exception is displayed under the corresponding execution.

Known limitations

Missing test file outcomes in Jest

Jest always reports the outcome of a test file as FAILED if at least one test case in the test file failed. If the error occurs in the file’s setup callback all the test cases in the test file are reported as FAILED. Such behavior does not allow to reliably determine whether the test file has failed due to the setup callback or due to the test cases themselves.

Users are advised to check the reported error messages to determine the root cause of the failure.

Incorrect console logs in highly interactive workloads

Currently, the Console Log section displays an interleaved version of stdout and stderr. In the vast majority of cases, this log will display an accurate representation of what users see as the output of their builds.

However, in some cases, tools will overwrite stderr while happily printing to stdout, or vice versa. In those cases, the captured console logs will be displayed incorrectly in the Console Log section.

For example, in the following screenshot, note the extra instances of RUNS:

This usually happens when running highly interactive workloads locally, such as long-running jest test suites. If this happens, the raw logs will contain an accurate, full representation of the command’s output.

Appendix A: Captured information

The Develocity npm agent captures information while npm is running and transmits it to Develocity after it has completed.

Most of the information captured can be considered to be build data. This includes the name of the projects in your build and more general environmental information, including your Node.js version, operating system, hardware, country, timezone and other things of this nature.

Notably, the actual source code being built and the output artifacts are not captured. However, error messages emitted by compilers or errors in tests may reveal aspects of the source code.

Listing

The list below details the notable information captured by the Develocity npm agent and transmitted in a Build Scan.

Environment
- Username (os.userInfo)
- Public hostname (os.hostname)
- Process
  - Node.js version
  - npm version
  - Locale
    
    Language
    
    Country
    
    Variant
    
    Timezone
- Operating System
  - Platform (os.platform)
  - Release (os.release)
  - Architecture (os.arch)
- Hardware
  - Number of processors (os.cpus)
Build
- Requested command, lifecycle script (if applicable), and arguments
- Console output (including exception messages and stack traces)
- Executed tests
  - Test framework (e.g. jest)
  - Test names (e.g. test file and test case name), outcome and duration
  - Console output
  - Failure error messages and stack traces

Access

Build Scans published to a Develocity installation are viewable by all users that can reach the server and have the required roles, should Identity Access Management (IAM) be turned on. Develocity provides a search interface for discovering and finding individual Build Scans.

Appendix B: Configuration reference

Required configuration

The only required configuration for the Develocity npm agent is the URL of the Develocity server that the Build Scan will be uploaded to. Publishing a Build Scan to scans.gradle.com is not supported.

This can be set through the configuration file or an environment variable.

Configuration file

(npm agent 0.10.0+)

A file named develocity.config.js or `develocity.config.cjs' can be used to configure the Develocity npm agent.

Configuration files using ESM or TypeScript are not supported.

The configuration file can be placed in the root of your project, together with the package.json file. If you have multiple packages that you want to share the same configuration, you can place the configuration file in a common parent directory.

The agent will look for the configuration file in the current working directory. If the current directory is a subdirectory of the user’s home and the configuration file cannot be found, the agent will try to locate the file one level up in the directory structure. The agent will continue until it finds the configuration file or reaches the user’s home directory.

packageJson.maxSizeBytes: The agent will attempt to read the package.json that defines your package to retrieve some data associated with your npm run. It will, however, refuse to read package.json files that exceed the configured maximum size. By default, it’s 1 MiB (1048576 bytes). It can be configured to a strictly positive number of bytes up to 1 GiB (1073741824 bytes). The number can also be provided as a string.
packageJson.searchBoundary: The agent will attempt to read the package.json that defines your package to retrieve some data associated with your npm run. If the package.json file cannot be found in the current working directory, the agent will attempt to walk up the directory structure to find it. By default, the agent will not try to walk up beyond a configurable search boundary. The agent will also not walk up the directory structure if the current working directory is not a subdirectory of the configured search boundary. By default, it’s the user’s home directory (as defined by os.homedir()). It can be configured to any absolute path. To remove any restriction, you can pass the root of your filesystem.
projectId: The Develocity project identifier. By default, the build will not be associated with any project. The documentation at the Project-level access control provides detailed information regarding project-level access control.

server.accessKey: A function that takes the hostname of the Develocity server and returns a string with the access key to use when connecting to that server, or undefined if there’s no suitable access key available for the provided host. If you use a properties file and/or want to retrieve the access keys from the same location as the Develocity Gradle plugin, consider using a helper. If the function throws an error, it will be logged, and the agent will not attempt to upload the Build Scan.
server.allowUntrustedServer: Allows to connect to an HTTPS Develocity server whose certificate is not trusted. This might be convenient when testing a deployment, but generally, it should not be used unless necessary. By default, it’s false. To take effect, the value must be exactly the boolean value true.

server.url: The URL of the Develocity server to which the Build Scan will be uploaded. It must be a valid URL with an HTTP or HTTPS scheme.
storageDirectory: The base directory where the Develocity npm agent stores temporary files. By default, it’s $HOME. You can read more about this in the relevant appendix.

Helpers

The Develocity npm agent provides some helpers to retrieve the access keys from the same location as the Develocity Gradle plugin. These helpers can be imported from the @gradle/develocity-agent/api/config package.

config.fromPropertiesFile

An implementation of the function expected by the server.accessKey configuration property that takes a function that provides a path to a properties file and returns the value associated with the relevant hostname, if available. The following example shows how to use this helper to retrieve the access keys from a known location:

const { fromPropertiesFile } = require('@gradle/develocity-agent/api/config');
const { resolve } = require('node:path');
const { homedir } = require('os');

module.exports = {
  server: {
    url: 'https://develocity.mycompany.com',
    accessKey: fromPropertiesFile(() => {
      return resolve(homedir(), '.develocity-keys.properties');
    }),
  },
}

config.inGradleUserHome

A function that resolves the path to the Develocity Gradle plugin user home directory and returns the path to the access keys file. It can be used in conjunction with the fromPropertiesFile helper to retrieve the access keys from the same location as the Develocity Gradle plugin, as in the following example:

const { fromPropertiesFile, inGradleUserHome } = require('@gradle/develocity-agent/api/config');

module.exports = {
  server: {
    url: 'https://develocity.mycompany.com',
    accessKey: fromPropertiesFile(inGradleUserHome()),
  },
}

Environment variables

All aspects of the Develocity npm agent can be configured with environment variables.

DEVELOCITY_ACCESS_KEY: A semi-colon-separated list of <host>=<key>. When connecting to <host>, <key> will be provided as an authentication token to the configured Develocity server. See DEVELOCITY_URL.
DEVELOCITY_ALLOW_UNTRUSTED_SERVER: Allows to connect to an HTTPS Develocity server whose certificate is not trusted. This might be convenient when testing a deployment, but in general should not be used unless absolutely necessary. By default, it’s false. To take effect, the value must be exactly true. See DEVELOCITY_URL.
DEVELOCITY_PACKAGE_JSON_MAX_SIZE_BYTES: The agent will attempt to read the package.json that defines your package to retrieve some data associated with your npm run. It will, however, refuse to read package.json files that exceed the configured maximum size. By default, it’s 1 MiB (1048576 bytes). It can be configured to a strictly positive number of bytes up to 1 GiB (1073741824 bytes).
DEVELOCITY_PACKAGE_JSON_SEARCH_BOUNDARY: The agent will attempt to read the package.json that defines your package to retrieve some data associated with your npm run. If the package.json file cannot be found in the current working directory, the agent will attempt to walk up the directory structure to find it. The agent will not try to walk up beyond a configurable search boundary by default. The agent will also not walk up the directory structure if the current working directory is not a subdirectory of the configured search boundary. By default, it’s the user’s home directory (as defined by os.homedir()). It can be configured to any absolute path. To remove any restriction, you can pass the root of your filesystem.
DEVELOCITY_PROJECT_ID: (npm agent 0.9.1+)

The Develocity project identifier. By default, the build will not be associated with any project. The documentation at the Project-level access control provides detailed information regarding project-level access control.
DEVELOCITY_STORAGE_DIRECTORY: The base directory where the Develocity npm agent stores temporary files. By default, it’s $HOME. You can read more about this in the relevant appendix.

DEVELOCITY_URL: The URL of the Develocity server to which the Build Scan will be uploaded. It must be a valid URL with an HTTP or HTTPS scheme.

The agent uses certain environment variables with the DEVELOCITY_INTERNAL_ prefix to perform its duties. Using any such key to alter the behavior of the agent is not supported and leads to undefined behavior.

Appendix C: Anatomy of the .develocity directory

By default, the Develocity npm agent stores temporary data in the ${user.home}/.develocity/npm directory. If you want to customize this location, use the storageDirectory configuration key:

module.exports = {
  storageDirectory: '/path/to/base/storage/directory',
}

Alternatively, use the DEVELOCITY_STORAGE_DIRECTORY environment variable:

export DEVELOCITY_STORAGE_DIRECTORY=/path/to/base/storage/directory

The directory may contain the following subdirectories:

build-scan-data: Data collected to create a Build Scan

The .develocity directory is an internal directory and subject to change without warning.

Appendix D: Release history

0.10.0

8th April 2025

[NEW] Build Scan: Test insights are available, supporting Jest
[NEW] The npm agent can now be configured with a JavaScript file
[FIX] Build Scan: Extra empty lines in the npm console output

Compatible with Develocity 2025.1 or later.

0.9.1

22nd January 2025

[NEW] Add support for project level access control

Compatible with Develocity 2024.3 or later.

0.9.0

12th December 2024

[NEW] Initial beta release compatible with Develocity 2024.3

Compatible with Develocity 2024.3 or later.

Appendix E: Release history (agent loader)

0.9.0

8th April 2025

Compatible with npm agent 0.10.0 or later.

Appendix F: Compatibility with npm and Develocity

Compatibility between versions of npm, Develocity, and the Develocity npm agent can be found in the compatibility matrix.

Appendix G: Verifying the signature of the agent package

The agent package is published alongside its signature. The public key is published to https://keys.openpgp.org. You can verify the signature as follows:

$ curl -OL https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-0.10.0.tgz && \
  curl -OL https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-0.10.0.tgz.asc && \
  gpg --keyserver keys.openpgp.org --recv-key  7B79ADD11F8A779FE90FD3D0893A028475557671 && \
  gpg --verify gradle-develocity-agent-0.10.0.tgz.asc gradle-develocity-agent-0.10.0.tgz

The output of the last command should look similar to the following:

gpg: Signature made Thu Sep 28 16:17:46 2023 CEST
gpg:                using RSA key 893A028475557671
gpg: Good signature from "Gradle Inc. <info@gradle.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7B79 ADD1 1F8A 779F E90F  D3D0 893A 0284 7555 7671

This verifies that the artifact was signed with the private key that corresponds to the imported public key. The warning is emitted because you haven’t explicitly trusted the imported key (hence [unknown]). One way of establishing trust is to verify the fingerprint over a secure channel. Please contact technical support should you wish to do so.