Configuring the Unified Agent for Gradle

The following article will include best practices and configuration recommendations for using the Unified Agent to scan Gradle projects.

Best Practices

Before scanning a Gradle project, ensure the following for the most accurate results:

  1. You have Gradle installed on the machine you are running the WhiteSource scan on.

  2. The project can be built successfully on the machine where you are running the scan.

  3. Your project has a build.gradle file available for scanning.

  4. Your project has a gradle wrapper if applicable.


Configuring UA Parameters

The following parameters should always be set to the following for the most accurate results:


gradle.localRepositoryPath - Set to the path to the local repository in the case that it is not in the default location.


Multi Module Parameters

gradle.aggregateModules - Set this to ‘true’ if you wish to aggregate all of your modules into one project.

gradle.innerModulesAsDependencies - Set this to false, if you wish to ignore and exclude all the modules dependencies from the resolution scan.

gradle.includeModules= Set this to the exact modules you wish to include.

gradle.excludeModules= Set this to the exact modules you wish to exclude


Additional Parameters

gradle.ignoreSourceFiles - Set to ‘true’ if you wish to ignore source files with extensions such as:".java", ".class".

gradle.runPreStep - Set to ‘true’ unless you have already built the project prior to the scan.

gradle.preferredEnvironment - Set this to 'gradle' if your project does not require Gradle wrapper commands to be built.

gradle.additionalArguments - Set to the parameters starting with ‘-' or '--’ that you would like to be added to the end of the Gradle commands during the scan. For example, --refresh-dependencies

gradle.includedConfigurations - Set this to dependency configurations you wish to include in the scan.

gradle.ignoredConfigurations - Set this to dependency configurations you wish to ignore in the scan.

Frequently Asked Questions

When the Unified Agent scan runs why does it copy libraries to temp folders and the Gradle cache?

When you have the parameter 'gradle.runPreStep' set to 'true' the Unified Agent completes the following in order to download the project's dependencies and scan the results:

For each build.gradle file that the Unified Agent finds:

  1. Unified Agent will copy the Gradle project to a temporary system folder

  2. Inside of each copied project's build.gradle file, the Unified Agent will add a task (named 'copyDependencies') in order to download the missing dependencies

  3. Unified Agent will run 'gradle copyDependencies' - this step will add the missing dependencies to the user's global cache

My project is taking too long to scan, is there a way to improve scan performance?

When the Unified Agent scan is running longer than expected, typically the Gradle pre-step and downloading of dependencies take up a significant portion of the scan time. To reduce scan time, we recommend that you ensure that all dependencies are available in the global cache prior to scanning. This will prevent the scan from needing to download missing dependencies. To reduce runtime even further, include a step prior to the scan that runs ‘gradle dependencies’ and moves the dependencies to the global cache and then set the parameter ‘gradle.runPreStep' to 'false’.


Additional Resources

You can find more information about scanning Gradle projects in the following document:

Unified Agent - documentation on how to use the Unified Agent