Software development is a team sport and Gradle Enterprise makes sharing and collaborating easier. This allows developers to unblock themselves, build teams to anticipate problems and deliver their services proactively, saving everyone time and money.

You can complete this tutorial in:

  • 1 minute (read the Introduction)

  • 5-10 minutes (read the Introduction and Tour)

  • 15-20 minutes (read the Introduction and Tour and perform the Hands-on Lab)

Introduction

In order for teams to understand what builds are happening, who is performing builds, how long they are taking, how often are they failing, and to provide the fine-grained details of all aspects of the configuration and execution of each task in your builds, a centralized service that stores detailed information about all builds is required.

Gradle Enterprise provides a service that does just this in conjunction with Gradle Build Tool via Builds Scans.

What are build scans?

  • A persistent record of what happened during a build

  • Permanent and shareable URLs that are "deep"

  • A resource to help developers help each other and unblock themselves

  • A resource for build and release engineers to accelerate debug time

Gradle Enterprise collects build scans of all of your builds and allows you to view, compare, analyze, share, and search for things like failed builds, execution time, dynamic dependencies, etc.

Here are some common use cases that Gradle Enterprise build scans help teams enable:

  1. I need help with a failed build or a question - I can message a deep link to a colleague

  2. What changed in my CI build between last week and this week?

  3. How many developers do I have performing builds?

  4. What are my failure rates? Are they different between dev and CI builds? How are failures split between test and non-test failures?

Perhaps most importantly, you will never have to re-run or reproduce anything ever again to figure out what is going on or to pull in a colleague to help. The build scan contains everything needed to diagnose any sort of issue and is typically (best practice) automatically generated and collected for each and every build the team performs.

Tour: Build scans for insights and collaboration

Share details of a build with a colleague

Let’s say that you are a build engineer or a developer, and you start to notice some output in the gradle output that you don’t understand, or that you suspect might be an anomaly. In the past, you might have tried to capture it by cutting and pasting the output into an email or chat window, but it would be difficult for others to directly help based on just that because there would be significant missing context to understand.

Now, with build scans, you can easily share a deep link to the specific detail you want to discuss.

Open this build scan to see for yourself.

This link takes us to the top level of the build scan which shows everything there is to know about the build. The thing I want to draw your attention to is a specific line of console output though, not the build as a whole, so I can instead navigate to a specific element and share the deep link, which is <LINK_TO_BUILD_SCAN_ITSELF>/console-log#<LINE_NUMBER>.

To see this in action, go directly to that element of the build scan with this link. Notice that this even highlights the specific line of console output in question. Line ranges can also be pre-selected.

The deep linking feature of build scans makes it easy for you to share any element of the build scan with colleagues through e-mail or messaging systems. This also allows for easy integration with systems such as ticketing systems, CI servers and online help forums.

And, you will never have to re-build something to get help or collect logs, increase logging levels, find the relevant output, or have to try to rebuild repeatedly because the failure isn’t a hard failure.

Understanding dependencies

Understanding what dependencies you have, what versions, and when new versions are selected, is a significant source of spent time and money for many teams. Gradle Enterprise gives you the tools needed to understand and gain insights into dependency graphs across all your projects, no matter how many or how complex or deeply nested.

Check if your code relies on a specific dependency and if so, on what version

We’d like to know if we have a certain dependency. Perhaps someone has asked if some project is being used, or a source code audit is being conducted. Consider this build scan. Picking up from the last example, we now know that we can go directly to the point of interest, which in this case is the dependency details.

We can see that the information on the entire transitive dependency graph goes on for many pages, and for a realistic build could go on for hundreds of pages, so we can search for the one we want. In this case, we want to know if we depend on (use) Google’s Guava libraries. In the Search box on top of the dependency tree, type "Guava". If the search box is not visible, just click on the magnifying glass icon at the top of the tree to cause it to become visible.

We can see that we do depend on Guava, in many places, and that the version of Guava that we depend on is 17.0. Just as important in some cases, you can see why the dependency comes in.

Understand why a given third-party library ends up on your classpath

In this example, we want to find out why additional logging libraries over those we expect to find are present in our build. Again, navigate to the dependencies section of the build scan and search for "log" (you will have to click the magnifying glass icon to make the search input box visible).

I know and expect to find the libraries slf4j and log4j but I do not expect to see commons-logging, yet there it is! The obvious question is, why is that there? If you click on the small icon displayed just to the right of the commons-logging entry when hovering it, you will see details, and then click Required By, and we can see that commons-logging was pulled in by our usage of the apache httpclient library.

We can now take measures to remediate this situation, for example by introducing a custom resolution strategy.

Find out which dependencies of your project use dynamic versions

Dynamic dependencies are a powerful tool but often cause unexpected issues with builds. Let’s say we want to audit a build to find out everything that is using dynamic dependencies, understand what versions are currently being selected, and determine if we want to change these to some less dynamic strategy. Consider this build. Again, navigate yourself to the Dependencies section of the build scan. Now click the icon at the top of the list that expands all dependencies. It looks like a list with a downward pointing arrow attached to its left side. You should now see the entire dependency graph.

Also, click the search icon (the magnifying glass) at the top of the list. You should now see two input fields. One is the search field which we have already considered. The other allows us to filter the tree by resolution filters. Using this control, specify "Resolution: Dynamic version".

You can now see all five dependencies (a subset of all dependencies) that are specified to be dynamic, and you can also see the version which was resolved at the time this build was performed.

Understand which Gradle plugins your build is using

Build engineers often want to know what Gradle plugins are in a particular build to find out what versions are used, which plugins are from Gradle, Inc., which are internally developed, and which are developed by third parties. The build scan provides the means to determine all of this and more from a single section of the build scan. Consider this build. Navigate to the Plugins section via the left-hand side section choices.

Here, in a single list view that spans all projects, we can easily see all three categories of plugins collected together, versions for the external plugins, and by clicking on each entry, we can see which projects are applying each plugin.

Hands-on Lab: Build scans for insights and collaboration

Read on to go one level deeper.

Prerequisites

To follow these steps, you will need:

  1. A zip file that includes the source code to recreate the build scans we discussed previously.
    You can get this from here.
    Unzip this anywhere, we will refer to that location as LAB_HOME in what follows.

  2. A local JVM installed.
    JVM requirements are specified at https://gradle.org/install. Note that a local Gradle Build Tool install is optional and not required. All hands-on labs will execute the Gradle Build Tool using the Gradle Wrapper.

  3. An instance of a Gradle Enterprise server.
    You can request a Gradle Enterprise trial here.

For the rest of the document, we will assume you have a Gradle Enterprise instance, available at https://gradle-enterprise.mycompany.com.

Lab: Inspect a build scan

Open a terminal window in LAB_HOME/02-browse-a-build-scan.

Using the text editor of your choice, modify the build scan configuration in build.gradle to point to your Gradle Enterprise server instance:

Replace
buildScan {
  server = '<<your Gradle Enterprise instance>>'
  publishAlways()
  allowUntrustedServer = true // Remove this if you don't use a self-signed or untrusted certificate
}
with
buildScan {
  server = 'https://gradle-enterprise.mycompany.com' // Your personal Gradle Enterprise instance
  publishAlways()
  allowUntrustedServer = true // Remove this if you don't use a self-signed or untrusted certificate
}

You will then follow the instructions as written in the file README.md

In this lab, you will run a build which will post a build scan to your Gradle Enterprise instance, and then find out some basic facts about your build environment, the same kinds of things that a team might want to find out. For example, since we store the JVM vendor and version, we can easily find out if all builds are using the same JVM, or if different ones are being used, which ones are out there, and where are the non-standard usages coming from, and then take actions to remediate any usage that is outside of current policies.

Lab: Find out if the developers in your company run the clean task

Open a terminal window in LAB_HOME/03-find-out-if-developers-run-clean.

You will then follow the instructions as written in the file README.md

In this lab, you will explore the searching capabilities of Gradle Enterprise, by filtering all builds that contain a "clean" task. You can and should explore the other filters available, like time range, username, and build outcome. These filters allow the most common sorts of filtering to be easily done.

Lab: See all builds that ran tests

Open a terminal window in LAB_HOME/04-see-all-builds-that-ran-tests.

Using the text editor of your choice, modify the build scan configuration in build.gradle to point to your Gradle Enterprise server instance in the same way we did for the first lab.

You will then follow the instructions as written in the file README.md

In this lab, you will use tags as a build scan search filter. Tags allow teams to add arbitrary information to the build scan that can make searching much more targeted and effective for the specific requirements and environmental information present in your environment.

Conclusion

Gradle Enterprise allows teams to more effectively share build results in order to debug and collaborate together, which allows you to spend less time debugging and reproducing problematic builds, and more time developing and delivering features that are useful to your customers and differentiated from your competition. The result is a substantial savings in time, which not only saves money but frees your most valuable resources from unpleasant and tedious work that adds no value to your business.