...
Info |
---|
With the release of the WhiteSource Unified Mend Unified Agent (previously called the File System Agent (FSA)), WhiteSource Mend will no longer provide standard support, including updates and fixes for the Maven plugin after May 4th, 2019. Extended Support (limited to configuration & support/troubleshooting) will be provided until November 1st, 2019. Please migrate to the Unified Agent before this date. This plugin will no longer be supported by WhiteSource Mend on November 2nd, 2019. The WhiteSource Mend Support team is ready to assist with the necessary changes required to use the Unified Agent and can be contacted via the Customer Community. Please note that, while Mend (formerly WhiteSource) has gone through a rebranding, the naming of the configurations have stayed the same to WhiteSource. |
Table of Contents |
---|
Overview
...
The maven plugin depends on the WhiteSource Mend agents API which uses the proxy-vole 20121203 library for auto proxy detection.
...
This is required when using version 1.1.7 and above of the maven Maven plugin.
Tip |
---|
Updated: Starting version 3.1.3 the proxy-vole library has been embedded into the maven plugin, no need to manually download and install into your local m2 repository. |
...
Code Block | ||
---|---|---|
| ||
<plugin> ... <configuration> ... <moduleTokens> <module_name_1>project_token_1</module_name_1> <module_name_2>project_token_2</module_name_2> </moduleTokens> </configuration> </plugin> |
Executing the Plugin
The whitesource Mend maven plugin achieves 2 goals:
...
The update goal sends an update request to WhiteSource Mend with the following cases:
You have no projects in WhiteSource Mend that are mapped to your maven project. The plugin will create a project for each module in WhiteSource Mend with all dependencies approved and populated in the project's inventory.
You already have a project in WhiteSource Mend that is mapped to your maven project. The plugin will create requests for new dependencies that don't exist in the WhiteSource Mend project's inventory.
Both cases can send a "check policies" request to WhiteSource Mend before sending the update request by setting the checkPolicies parameter to true, if any new dependency doesn't comply with your organization's policies, the update request will not be sent.
...
The checkPolicies goal simply sends a check policies request to WhiteSource Mend without sending the update request afterwards if all dependencies comply with your organization's policies.
...
The plugin configuration is flexible and can be customized for the cases when a simple configuration like the one suggested above is not sufficient to your needs.
Required Parameters
Name | Type | Description | -D Parameter |
---|---|---|---|
String | Unique identifier of the organization to update, also known as 'API Token'. | org.whitesource.orgToken Since version 3.1.6 |
Optional Parameters
Name | Type | Description | -D Parameter | ||
---|---|---|---|---|---|
| String | Set logging datetime format. Default value is [HH:mm:ss] | org.whitesource.timeFormat Since version 17.11.3 | ||
Boolean | Set to true to check policies before update. | org.whitesource.checkPolicies Since version 3.1.6 | |||
forceCheckAllDependencies | Boolean | Optional. Set to true to force check all policies for all dependencies, used only if checkPolicies is set to true. |
Mend projects. | org.whitesource.forceCheckAllDependencies Since version 3.1.7 | ||||
forceUpdate | Boolean | Optional. Updates organization inventory regardless of policy violations. | org.whitesource.forceUpdate Since version 3.2.8 | ||
String | Product name or token. | org.whitesource.product Since version 3.2.8 | |||
String | Product version. Use this to override the version in each module. | org.whitesource.productVersion Since version 3.2.8 | |||
String | Unique identifier of the White Source project to update. If omitted, default naming convention will apply. | ||||
Map | Map of module artifactId to White Source project token. See example | ||||
String[] | Only modules with an artifactId matching one of these patterns will be processed by the plugin. Should be used like this:
| ||||
String[] | Modules with an artifactId matching any of these patterns will not be processed by the plugin. Should be used like this:
| ||||
Boolean | Set to true to ignore this maven project. Overrides any include patterns. | ||||
Boolean | Set to true to ignore this maven modules of type pom. | org.whitesource.ignorePomModules Since version 3.2.8 | |||
ignoredScopes | String[] | By default the maven plugin ignores direct dependencies with scope 'test' and 'provided'. | org.whitesource.ignoredScopes Since version 3.3.1 | ||
Boolean | Indicates whether the build will continue even if there are errors. | org.whitesource.failOnError Since version 3.2.8 | |||
Boolean | Set to true to skip the maven execution. | ||||
Boolean | Set to true to create the check policies report as a text file in JSON format instead of the regular HTML format report. | ||||
Boolean | Set to true to combine all pom modules into a single |
Mend project with an aggregated dependency flat list (no hierarchy). | org.whitesource.aggregateModules Since version 3.2.8 | ||
preserveModuleInfo | Boolean | Optional. Works only if the 'aggregateModules' parameter is set to 'true'. It creates a hierarchy tree for modules that appear in the root POM. | org.whitesource.preserveModuleInfo Since version 18.5.2 |
aggregateProjectName | String | Optional. The project name that will appear in |
Mend. If omitted and no project token defined, defaults to pom artifactId. | org.whitesource.aggregateProjectName Since version 3.2.8 | ||
aggregateProjectToken | String | Optional. Unique identifier of the White Source project to update, overrides aggregateProjectName. If omitted, default naming convention will apply. | org.whitesource.aggregateProjectToken Since version 3.2.8 |
requesterEmail | String | Optional. The provided email will be matched with an existing |
Mend account. Requests for new libraries will be created with the matched account as the requester. | org.whitesource.requesterEmail Since version 3.2.8 | ||
autoDetectProxySettings | Boolean | Indicates whether to try to detect proxy configuration in the underlying machine (e.g. in OS proxy settings, in JVM system properties etc.) | org.whitesource.autoDetectProxySettings Since version 3.2.8 |
connectionTimeoutMinutes | int | Connection timeout in minutes. | wss.connectionTimeoutMinutes Since version 3.2.7 |
ignoreDependencyResolutionErrors | Boolean | Indicates whether to ignore an error while resolving dependencies for a module, this module will not be included in the scan and will not appear as a project within |
Mend. | org.whitesource.ignoreDependencyResolutionErrors Since version 3.3.0 | |
failOnConnectionError | Boolean | Fails the build when unable to connect to |
Mend service | org.whitesource.failOnConnectionError Since version 3.3.1 | |
connectionRetries | int | Connection retries when unable to connect to |
Mend service. | org.whitesource.connectionRetries Since version 3.3.1 | ||
orgTokenFile | String | Optional. Path to file that contains the org token. Use this to override the orgToken parameter in the pom.xml file. | org.whitesource.orgTokenFile Since version 18.2.2 |
userKey | String | Unique identifier of user, can be generate from the profile page in your |
Mend account. Required if |
Mend administrator has enabled "Enforce user level access" option. | org.whitesource.userKey Since version 18.4.2 | ||
userKeyFile | String | Optional. Path to file that contains the userKey . Use this to override the userKey parameter in the pom.xml file. | org.whitesource.userKeyFile Since version 18.4.2 |
updateEmptyProject | Boolean | Optional. Whether or not to upload/update an empty project | org.whitesource.updateEmptyProject Since version 19.5.1 |
Tip |
---|
If you didn't find what you need, you can try the plugin documentation or drop a line to our support team. |
Check Policies Report
The generated check policies report is located in project_location\target\site\whitesource, there are two types of report formats:
...
The plugin generates a test file in JSON format that represents the WhiteSource Mend agents API CheckPoliciesResult object.
...
By default the maven plugin doesn't send information regarding direct dependencies with scope 'test' and 'provided' to WhiteSourceMend.
To override ignoring direct dependencies with scope 'provided' enter the following configuration:
...
Then change the Maven Dependency Resolution Settings in the Admin section in WhiteSourceMend, uncheck "Ignore Provided Scope Direct Dependencies".
...
By default the maven plugin creates a WhiteSource Mend project for each module in you POM structure.
In order to create a single WhiteSource Mend project that aggregates dependencies from all modules (without hierarchy) use the aggregateModules property:
...
Using the requesterEmail parameter, the provided email will be matched with an existing WhiteSource Mend account. Requests for new libraries will be created with the matched account as the requester.
Note |
---|
This will only work with the email you use to sign in to your WhiteSource Mend account, in case you're using social login use your social email address. |
...
Setting 'forceCheckAllDependencies' tag to true will force check all policies for all dependencies introduced to the WhiteSource Mend projects.
Setting 'forceCheckAllDependencies' tag to false or not using it at all will check only the new dependencies introduced to the WhiteSource Mend projects.
Copy & paste the following snippet into the plugins section in your parent pom.xml file.
Code Block | ||
---|---|---|
| ||
<plugin> <groupId>org.whitesource</groupId> <artifactId>whitesource-maven-plugin</artifactId> <version>18.4.2</version> <configuration> <orgToken>Your organization token</orgToken> <checkPolicies>true</checkPolicies> <forceUpdate>true</forceUpdate> <forceCheckAllDependencies>true</forceCheckAllDependencies> </configuration> </plugin> |
Release Notes
Version | Content |
---|---|
Version 20.7.1 |
|
| |
Version 19.5.1 |
|
Version 18.11.1 |
|
Version 18.6.2 |
|
Version 18.5.1 |
|
Version 18.4.2 |
|
Version 18.4.1 |
|
Version 18.2.2 |
|
Version 18.1.3 |
|
Version 17.11.3 |
|
Version 3.3.1 |
|
| |||
Version 3.3.0 | Add property ignoreDependencyResolutionErrors for ignoring modules where dependency resolution failed, false by default.
|
To enable add the following line to the |
Mend maven plugin configuration:
or via command line:
| ||||
Version 3.2.9 | Fix incorrect message when skipping an excluded module. | |||
Version 3.2.8 | Read the following properties from command line using -D:
| |||
Version 3.2.7 | Add parameter 'connectionTimeoutMinutes'. | |||
Version 3.2.6 | Bug fix for 'includes' parameter. | |||
Version 3.2.5 | Fail the build upon policy violation if 'failOnError' is enabled and 'forceUpdate' is enabled. | |||
Version 3.2.4 | Add force update functionality - inventory update regardless of policy violations. | |||
Version 3.2.3 | Improve exceptions handling. | |||
Version 3.2.2 | Generate a policy rejection summary in JSON format (named 'policyRejectionSummary.json') after policies are checked. This is the JSON format:
| |||
Version 3.2.1 | Auto-detect proxy settings only when requested (via autoDetectProxySettings parameter) | |||
Version 3.1.7 | Add the ability to choose which dependencies (all / new) using will be checked when setting checkPolicies to true, using the forceCheckAllDependencies property. | |||
Version 3.1.6 | Define orgToken and checkPolicies as -D parameters (with "org.whitesource." as prefix). | |||
Version 3.1.5 | Add and change logs. | |||
Version 3.1.4 | Add requester email as parameter. | |||
Version 3.1.3 | Embedded proxy-vole library, no need to manually download and install into your local m2 repository. | |||
Version 3.1.2 | Simplified aggreateModules property to allow passing values via command line. | |||
Version 3.1.1 | Added option to aggregate pom modules into a single |
Mend project.
| |||
Version 3.1 | Minor bug fixes. | ||
Version 3.0 | Support for maven versions 3.0.x, 3.1.x and 3.2.x | ||
Version 2.1.0 | Implement client-side dependency resolution.
| ||
Version 2.0.1 | Added option to resolve in-house dependencies. Should only be used if any internal (in-house) dependencies appear in your project and in-house rules exist in your |
Mend account.
| |||
Version 1.1.9 | Added checkPolicies goal. Support for report as text file in JSON format.
| ||
Version 1.1.8 | Support for dependency exclusions. Ignore test scope direct dependencies (don't send them to |
Mend).
| |||
Version 1.1.7 | Auto proxy detection in agent client.
| ||
Version 1.1.6 |
|