IMPORTANT: The Jenkins plugin will reach its End Of Life starting August 1, 2022. After this date, WhiteSource will no longer provide standard support, including updates and fixes, for the deprecated plugin. Extended Support, which is limited to configuration and Support troubleshooting, will continue until February 1, 2023. Following this date, the Jenkins plugin will no longer be supported by WhiteSource. Please make sure to migrate to the Unified Agent before the end of standard support on August 1, 2022 to maintain full support of your product. |
The plugin integrates automatic open source management with Jenkins.
Once set up, all usage of open-source software in the organization will be continuously and automatically synchronized with WhiteSource:
New projects will be created
Existing projects will be updated
Policies will be enforced on every action, failing the build if necessary.
Supported since version 1.7. For previous versions of Jenkins plugin click here.
The plugin currently supports maven, freestyle jobs and maven pipeline jobs. |
The plugin is licensed under the Apache 2.0 license. Source code and issues are hosted on github.
Before you begin, note the following:
The native Jenkins plugin does not support NPM resolution through package.json.
The Jenkins plugin documentation contains documentation for General or Maven jobs only.
The Jenkins plugin is useful for Maven projects or for source file scanning.
Once the build is finished, the plugin will determine which open source is currently used by your project and send it to WhiteSource.
No source code is scanned. Only descriptive information is sent to WhiteSource. |
WhiteSource uses the collected information to create new projects or update existing ones.
The plugin checks each new library against the organizational policies. If a library is automatically rejected by a policy then the build fails. Otherwise, your account is updated.
An informative report of the results is generated, regardless of the outcome.
The report files are saved in:
$JENKINS_HOME\jobs\<job name>\\builds\<build YYYY-MM-DD_HH-mm-ss>\whitesource
Go to Manage Jenkins > Manage Plugins > Available.
Search for WhiteSource, select the checkbox, and click Install.
Start by configuring the global settings. These settings will apply across all jobs on this Jenkins master. Then setup the jobs which should interact with WhiteSource.
Once the plugin is installed, go to Manage Jenkins > Configure System.
Go to the WhiteSource section.
Selecting the Fail on error checkbox instructs to fail the build on a general error (e.g., network error) or a policy violation.
Clearing this checkbox indicates that the plugin fails the build only for policy violations.
Connection timeout is measured in minutes. Default value is 60 minutes.
A unique identifier of the organization. You can receive an API token in the administration section of your WhiteSource account.
URL to where the request is sent.
Use the WhiteSource Server URL which can be retrieved from your Profile page on the Server URLs panel. For example: "https://saas.whitesourcesoftware.com".
Check that the introduced open source libraries conform with organization policies.
Check only new libraries - Check that the newly introduced open source libraries conform with organization policies.
Force check all libraries - Check that all introduced open-source libraries conform with organization policies.
Disable - Disable policies check when updating WhiteSource.
Proxy settings The plugin uses the same proxy configuration used by Jenkins to send information to WhiteSource. |
For each job you want to use the plugin for, you need to add a post-build action. In job configuration
These fields are common to all job types. They are mainly here to allow different values for global settings.
Parameter | Description | Environment variable support |
---|---|---|
Product name or Token | Name or token to uniquely identify the product to update. | Yes |
Product version | Version of the product to update. | Yes |
Check only new libraries | Optionally override this property from global configuration. | Yes |
Force check all libraries | Optionally override this property from global configuration. | No |
Force update | Updates organization inventory regardless of policy violations. | No |
Override API token | Optionally override this property from Global WhiteSource Configuration. | Yes |
Override userKey | Unique identifier of user, can be generate from the profile page in your whitesource account. | Yes |
Project token | Unique identifier of the White Source project to update. If omitted, default naming convention will apply. | Yes |
Requester email | Email of the WhiteSource user that requests to update WhiteSource. | Yes |
Connection Retries | Connection retries when unable to connect to WhiteSource service. | Yes |
Connection Retries Interval | Wait time between connection retries. | Yes |
* Environment variable support from version 1.8.1
Normally, for maven 2/3 jobs, no extra configuration is required.
However, if you do need more control on the plugin behavior, click on Advanced to show more options.
Parameter | Description |
---|---|
Module tokens | Map of module artifactId to WhiteSource project token. |
Modules to include | Only modules with an artifactId matching one of these patterns will be processed by the plugin. |
Modules to exclude | Modules with an artifactId matching any of these patterns will not be processed by the plugin. |
Ignore pom modules | Set to true to ignore this maven modules of type pom. |
Connection Retries | Connection retries when unable to connect to WhiteSource service (default value is 1). |
Connection Retries Interval | Connection interval in seconds between two connection retries to WhiteSource service (default value is: 3 seconds). |
Projects with no concise system for managing dependencies, like maven, require different configuration.
What we're looking for is descriptive information about each library used. What we need to know is which libraries to include and where we can find them, that is the sole purpose of the configuration.
Parameter | Meaning | Environment variable support |
---|---|---|
Includes | Comma, space or line separated list of Ant style GLOB patterns specifying which files to include in scan. | Yes |
Excludes | Comma, space or line separated list of Ant style GLOB patterns specifying which files to exclude form scan. | Yes |
*Environment variable support from version 1.8.1
Currently we support the following file extensions:
jar, aar, dll, tar.gz, egg, whl, rpm, tar.bz2, tgz, deb, gzip, gem, swf, swc
c, cc, cp, cpp, cxx, c++, go, goc, h, hpp, hxx, m, mm, c#, cs, csharp, java, js, php, py, rb, swift
In order to use the WhiteSource Jenkins plugin, the following is required:
Jenkins version 2.x or later.
Pipeline plugin installed.
WhiteSource plugin version 1.8.x or later.
The Pipeline support also consists of Global WhiteSource Configuration:
And the job configuration, which is available when selecting the WhiteSource plugin inside the snippet generator:
After filling the desired fields, click Generate Groovy, and a groovy script will be generated, according to the specific job configuration.
Add the generated script to any build step inside your Jenkins Pipeline script file:
node { stage ('Build') { withMaven( maven: 'maven', mavenSettingsFilePath: 'path-to/settings.xml', mavenLocalRepo:'~/.m2/repository') { whitesource jobApiToken: 'api-token', jobUserKey:'user-key', libIncludes: '**/*.jar **/*.js', libExcludes: '', product: 'FT', productVersion: '', projectToken: '', requesterEmail: '' } } } |
https://updates.jenkins.io/download/plugins/whitesource/
Version | Features | Release Date |
---|---|---|
20.8.1 |
| |
19.1.1 |
|
|
18.10.2 |
| |
18.10.1 |
| |
18.8.2 |
| |
18.6.3 |
| |
18.6.2 |
| |
18.5.2 |
| |
18.5.1 |
|
|
18.1.3 | Add support for Jenkins 2.102 |
|
18.1.1 | Bug fix - Freestyle job runinng |
|
17.12.1 | Add support for maven pipeline job |
|
17.11.4 | Minor fixes |
|
1.8.2 | Bug fix - NPE exception on enviroment variables |
|
1.8.1 | Add support for enviroment variables |
|
1.8.0 | Minor fixes - remove jelly importing |
|
1.7.9 | Add support for generic pipeline job |
|
1.7.8 | Enable build failure on policy violation (even when force update is enabled) |
|
1.7.7 | Bug fix - ignore for pom modules field |
|
1.7.6 | Add force update option |
|
1.7.5 | Bug fix - save proxy port |
|
1.7.4 | Bug fix - fixing possible NPEs |
|
1.7.3 | Minor fixes |
|
1.7.2 | Move to JDK 1.7 |
|
1.7.1 | Bug fix - includes/excludes parameter in generic job |
|
1.7 | Add check policies for all libraries |
|
1.5.2 | Add fail on error param to global config |
|
1.5.1 | Update latest version of maven-release-plugin |
|
1.4 | Fix for proxy configuration |
|
1.3 |
|
|
1.2 | Shelved version. Disregard |
|
1.1 | Minor changes:
|
|
1.0 | First release of the plugin |
|