Jenkins Plugin

 

General Information

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.

How it Works

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.

Normal Flow

WhiteSource uses the collected information to create new projects or update existing ones.

Policy Check Flow

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

Installing The Plugin

  1. Go to Manage Jenkins > Manage Plugins > Available.

  2. Search for WhiteSource, select the checkbox, and click Install.

Using The Plugin

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.

Global WhiteSource Configuration

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.

API Token

A unique identifier of the organization. You can receive an API token in the administration section of your WhiteSource account.

Service url

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 policy compliance

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.

Job Specific Settings

For each job you want to use the plugin for, you need to add a post-build action. In job configuration 

Common 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

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

Maven Jobs

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

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).

Freestyle Jobs

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

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

Supported Extension Types

Currently we support the following file extensions:

Binary File Extensions

jar, aar, dll, tar.gz, egg, whl, rpm, tar.bz2, tgz, deb, gzip, gem, swf, swc

Source File Extensions

c, cc, cp, cpp, cxx, c++, go, goc, h, hpp, hxx, m, mm, c#, cs, csharp, java, js, php, py, rb, swift

Pipeline Support

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:

Add the Generated Script

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:

Maven pipeline 

Pipeline step sample
1 2 3 4 5 6 7 8 9 10 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/

Change Log

Version

Features

Release Date

Version

Features

Release Date

20.8.1

Sep 2, 2020

19.1.1

  • Update agents version

Jan 27, 2019 

18.10.2

  • Minor bug fixes

Nov 4, 2018

18.10.1

  • Minor bug fix - fix text message

  • Support both service URL with and without "/agent"  

Oct 21, 2018

18.8.2

  • Minor bug fixes

Sep 2, 2018

18.6.3

  • Minor bug fixes

Jul 8, 2018

18.6.2

  • Resume Build upon failed communication to server

Jun 24, 2018

18.5.2

  • Bug fix - using project token as identifier.

Jun 10, 2018

18.5.1

  • Added support for user-level access control in integrations

  • Minor fixes.

May 27, 2018 

18.1.3

Add support for Jenkins 2.102

Feb 7, 2018 

18.1.1

Bug fix - Freestyle job runinng

Jan 18, 2017 

17.12.1

Add support  for maven pipeline job

Dec 10, 2017 

17.11.4

Minor fixes

Dec 3, 2017 

1.8.2

Bug fix - NPE exception on enviroment variables

Jul 23, 2017 

1.8.1

Add support for enviroment variables

Jul 12, 2017 

1.8.0

Minor fixes - remove jelly importing

Jun 6, 2017 

1.7.9

Add support for generic pipeline job

Jun 4, 2017 

1.7.8

Enable build failure on policy violation (even when force update is enabled)

May 10, 2017 

1.7.7

Bug fix - ignore for pom modules field

Feb 28, 2017 

1.7.6

Add force update option

Feb 28, 2017 

1.7.5

Bug fix - save proxy port

Jan 24, 2017 

1.7.4

Bug fix - fixing possible NPEs

Jan 3, 2017 

1.7.3

Minor fixes

Jan 3, 2017 

1.7.2

Move to JDK 1.7

Jun 26, 2016 

1.7.1

Bug fix - includes/excludes parameter in generic job

Feb 29, 2016 

1.7

Add check policies for all libraries

Feb 22, 2016 

1.5.2

Add fail on error param to global config

Jan 12, 2016 

1.5.1

Update latest version of maven-release-plugin

Feb 22, 2015 

1.4

Fix for proxy configuration

Aug 8, 2013 

1.3

  • Product identification

  • Well known file extensions are now scanned by default in free style jobs

  • Bug fixes

Aug 5, 2013 

1.2

Shelved version. Disregard

Aug 5, 2013 

1.1

Minor changes:

  • Communication with White Source servers is now encrypted using SSL by default

  • Several bug fixes in policy check report

Mar 24, 2013 

1.0

First release of the plugin

Oct 28, 2012