Issue Tracker Integration Generic Platform and Plugins

Overview

This integration is currently in beta.

WhiteSource provides the ability to integrate with issue tracking systems, in order to automatically create issues in those systems when a policy match occurs. As a result, issues automatically open in the issue tracking system, and are automatically filled with the relevant WhiteSource information required to mitigate the risks triggering the creation of the issue.

This integration is implemented as a generic platform, exposed by external/public APIs, whereupon WhiteSource provides a set of out-of-the-box plugins for specific common Issue tracking systems. The triggering for the issues' creation occurs when a policy of the type “Issue” is matched with a library. This occurs no matter which plugins you are using.

NOTE: If you have already defined a previous integration of WhiteSource with an issue tracking system, and created policies to trigger issues creation, it can continue working “side by side” with the new integration until the “old” one will be deprecated. Ensure you define new policies for the new integration. To view the documentation for the legacy issue tracker integration, click here.

Jira Server Plugin

Overview

The Jira Server Plugin, supporting integration with the Jira Server solution, is currently the first to be released out of a planned set of out-of-the-box plugins. The Jira plugin is based on matches of the “Issue” policy type with relevant libraries and creates the corresponding issues in Jira.

Prerequisites

To configure the integration, ensure the following:

  • Jira Server versions from 7.13 to 8.15

  • Admin permissions to Jira

  • Admin permissions to WhiteSource

How the Jira Plugin Works

The Jira Server Plugin integration works the following way:

  1. The Jira server plugin periodically queries the WhiteSource application for “Issue” Policy matches. These matches represent Issues the plugin should create in Jira.

  2. The corresponding WhiteSource Issue (of type WS_Issue) is created in Jira with all the relevant information in dedicated fields that can be sorted and filtered.

  3. The Jira plugin will in turn update the application regarding Issue changes and their statuses.

Installing and Configuring the Plugin

To install and configure the plugin, do as follows:

  1. Log into Jira with Admin permissions.

  2. Navigate to Manage Apps in the JIRA ADMINISTRATION section.

  3. Search for WhiteSource in the Atlassian Marketplace search box.

  4. Find the WhiteSource Integration for Jira and click Install.

  5. After the installation, you will be directed to the configuration page. (If not, in the User-Installed Apps list, navigate to the WhiteSource Jira Plugin and click Configure).

  6. The Validate your WhiteSource License screen is displayed. Enter the activation key (to generate an activation key, refer here) in the provided box, and click Verify. In case you are using a proxy, press the Show Proxy Settings button to set it up.
    NOTE: If the activation key cannot be verified, it might be expired or you might be experiencing connectivity issues. Contact Support.

  7. If a verification indication is displayed, click Next. The plugin mapping screen is displayed. Continue to Mapping the WhiteSource Projects to the Jira Projects.

Mapping the WhiteSource Projects to the Jira Projects

In the plugin mapping screen, you can define (or map) in which Jira projects the Issues will be created according to the relevant WhiteSource scope.

To map the WhiteSource projects to the Jira projects, do as follows:

If no mapping is done, the ticket will be opened in the default Jira ticket board.

  1. Map the WhiteSource projects to the Jira projects in which the issues will be created, according to the WhiteSource scope and the match type.

    • In WS Product, select the product.

    • In WS Project, select one or more projects, or select Select All.

    • In WS Policy Match, create a mapping of all relevant policy matches for the project (for example, By License Group, Security Vulnerability Severity, etc.).

    • In Jira Project, select the relevant Jira projects for your mapping.

  2. Ensure that you select a default Jira project in which Issues without a specific mapping will be created.

  3. Click Save.

Creating a Policy to Trigger Issues

To create a policy to trigger issues, do as follows:

  1. To create a policy that will trigger issues, open the Policy page.

  2. You can create a policy on any level but it must correspond to the mapping.

  3. Click Add Policy.

  4. Create the policy as needed. In Action, select Issue.

  5. In Issue Settings, in Tracker Type, select Jira Plugin.

  6. Click Save.

When the policy will be matched with a library (as a result of the scan or when applying to existing inventory), the issue creation will be triggered. When the plugin fetches the information (once an hour) you will be able to see the created issues in your Jira projects.

Jira Cloud Plugin

Future versions of WhiteSource will introduce a Jira Cloud Plugin.

Creating Your Own Plugin

A plugin can be created by any customer with access to the API.

TBD - future versions of WhiteSource will enable you to create your own plugins.

Appendix: Generating an Activation Key

To generate an activation key, do as follows:

This procedure enables you to create a token with which to validate the Jira integration.

  1. In the WhiteSource application, click Admin. The Organization Administration screen is displayed.

  2. In the Integration area, click Issue Tracker Settings. The Issue Tracker Settings screen is displayed.

  3. In Jira Server Plugin Integration, click Generate Activation Key. Copy the key for later use.