This guide covers how to get started with Develocity, with topics such as strategies for incrementally introducing Build Scans usage, and key Build Scan features for improving your development productivity.
Develocity provides Build Scan, a permanent and shareable record of an executed build that allows collaborative troubleshooting and optimization.
Installation
This guide does not cover installation of Develocity. Please consult one of the following installation manuals for help with installation:
The remainder of this guide will assume that your installation has a public hostname of develocity.mycompany.com and has enabled HTTPS.
Develocity npm agent
To use Build Scans, you must apply the Develocity npm agent to your project.
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 testPublishing 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
Add the following to
.env
Setup an alias for npm
|
|
You might encounter a warning about an untrusted certificate when connecting to Develocity over HTTPS. The ideal solution is for someone to add a valid SSL certificate to the Develocity instance, but we recognize that you may not be able to do that. In this case, set the This is a convenient workaround, but you shouldn’t use it as a long-term solution. |
More detailed information about the Develocity npm agent can be found in the Develocity npm agent user manual.
Build Scan
Build Scans are a significant innovation in software build tooling. Having centralized and shareable records providing fine-grained details and insights of all builds, including local development builds, enables new levels of collaborative debugging and optimization.
Quick start
Build Scans are automatically enabled for all builds, when applying the Develocity npm agent. As the build completes, the last lines of output will be similar to:
Publishing build scan... https://develocity.mycompany.com/s/3z475bz247h5g
Follow that link to view your Build Scan.
Build Scan highlights
This section calls out a subset of the things that you can do with Build Scans.
Find and view any Build Scan
Search through all the captured Build Scans by going to https://develocity.mycompany.com/scans.
This view allows searching by various criteria, including top-level project name, username, build outcome, build start time and more. By default, the list is sorted to show the most recent scans first.
Beyond looking for a particular Build Scan, the listing can provide new insights into the actual builds being run at your organization and by your colleagues. You might find occurrences of previously unknown errors with your build, or that the build is taking longer in certain cases than you expected, or that certain build users are executing more goals than they need to and are therefore subjecting themselves to more build time than they need to, and other previously unknown behaviors.
Inspect console log
The console log will be included in your Build Scan. Use the left navigation menu to visit the Console Log section.
This section will display all the console log emitted by the instrumented npm process, as well as any process it spawned to perform some particular task (in the example above, npm test ran jest).
Next steps
Custom tags, values and links
Build Scans can be enriched with metadata particular to your environment by several means.
Extending your Build Scans with tags, values and links is strongly recommended. In particular:
-
VCS information such as commit identifiers, branch names, etc.
-
Tags for different types of builds (for example,
CIvs.local) -
Links to CI system record of build for CI builds
This adds useful context to your Build Scans.
Integrating your CI tool
Build Scans are passive with regard to the build process. That is, enabling Build Scans does not affect the outcome or outputs of your build. As such, it is generally safe to simply add the necessary configuration to your projects to enable sending Build Scans to your Develocity installation and check it in to version control, enabling it for all users of the build.
The Develocity npm agent will not cause build failures, even when there is no connection available to the Develocity server when trying to publish.
Getting help or asking questions
If you are currently using Develocity as part of your trial sign-up or license purchase, you will have received instructions on how to access the priority Develocity support channel. If you have any issues with or questions about Develocity, please raise a support request.
Alternatively, or if you are not yet using Develocity, you can use our contact form.
Keeping up to date
Develocity is constantly evolving with regular updates that add new features and capabilities. The monthly Gradle newsletter is an easy way to stay informed about new releases, features and events.