The Develocity npm agent improves your development workflow and your productivity, when developing and maintaining Node.js projects. The agent enables Build Scan insights.

Getting set up

Setup

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

To collect data from npm invocations, the agent needs to be preloaded.

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

NODE_OPTIONS='-r @gradle/develocity-agent/preload' npm test

Publishing a Build Scan to scans.gradle.com is not supported. The minimum configuration required is the Develocity server URL.

The agent is configured through environment variables. Use DEVELOCITY_URL to set the Develocity server URL:

DEVELOCITY_URL=https://develocity.mycompany.com NODE_OPTIONS='-r @gradle/develocity-agent/preload' npm test

Passing environment variables on every call can be tedious and verbose. A common practice to make this more convenient is to use a .env files to store environment variables. A widely-adopted tool to manage these files is dotenvx.

Add the following to .env 
NODE_OPTIONS='-r @gradle/develocity-agent/preload'
DEVELOCITY_URL=https://develocity.mycompany.com
Setup an alias for npm 
alias npm="dotenvx run npm"

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.

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:

  1. Get an access key or access token for the user you wish 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 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.

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.

build scan service overview
Figure 1. Build Scans can be published to Develocity

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:

scan with custom data
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":

build scan filtered list
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, 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

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.

To add a link, 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, 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

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

  • Build

    • Requested command, lifecycle script (if applicable), and arguments

    • Console output (including exception 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

Environment variables

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

Required

DEVELOCITY_URL

The URL of the Develocity server that the Build Scan will be uploaded to.

Optional

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

In order to retrieve some data associated with your npm run, the agent will attempt to read the package.json that defines your package. 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

In order to retrieve some data associated with your npm run, the agent will attempt to read the package.json that defines your package. 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.

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.

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

12th December 2024

  • [NEW] Initial beta release compatible with Develocity 2024.3

Compatible with Develocity 2024.3 or later.

Appendix E: Compatibility with npm and Develocity

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

Appendix F: 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.9.0.tgz && \
  curl -OL https://develocity-npm-pkgs.gradle.com/gradle-develocity-agent-0.9.0.tgz.asc && \
  gpg --keyserver keys.openpgp.org --recv-key  7B79ADD11F8A779FE90FD3D0893A028475557671 && \
  gpg --verify gradle-develocity-agent-0.9.0.tgz.asc gradle-develocity-agent-0.9.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:                 aka "Gradle Inc. <maven-publishing@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.