Documentation Nexus IQ Server 1.31

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

17.2. Integrating Nexus IQ for Hudson/Jenkins 1.x

Nexus IQ for Hudson/Jenkins 1.x evaluates the project workspace after a build for all supported component types, creates a summary file about all the components found and submits that to the IQ Server. The IQ Server uses that data to produce an analysis with the security and license information and send it back to the CI server. It will then use these results to render the analysis reports.

The file types supported for analysis are in tar/zip like format with the extensions tar, tar.bz2, tb2, tbz, tar.gz, tgz and zip or in Java archive formats of the type jar, ear, war, hpi, wsr, har, sar, rar, mar and nbm.

Historically the Hudson project and community split into two groups, with Jenkins as well as Hudson emerging as sibling products with a different focus going forward while sharing a common API for plugins. In general, with regard to the IQ for Hudson/Jenkins functionality, the interaction will be near identical, with only a few differences, which are inherent to Hudson and Jenkins, and not IQ Server.

17.2.1. Installation

Nexus IQ for Hudson/Jenkins 1.x is distributed as a Hudson plugin package (.hpi file) and is compatible with Jenkins and Hudson. Download the plugin from Sonatype Support.

In order to install the plugin, log into Jenkins or Hudson as an administrator and then select Manage Jenkins/Manage Hudson to get to the global configuration menu displayed in Figure 17.1, “Jenkins Global Configuration Menu” in the Jenkins look. The Hudson look will be similar in content, yet different in colors and styling.

figs/web/ci-jenkins-manage.png

Figure 17.1. Jenkins Global Configuration Menu


From the displayed configuration menu, select Manage Plugins and in the plugin management section, choose the Advanced tab.

The advanced plugin management allows you to upload a plugin distribution file (.hpi) in the section entitled Manual Plugin Installation on Hudson and Upload Plugin on Jenkins. Click Choose File and select Nexus IQ for Hudson/Jenkins 1.x hpi file named nexus-iq-jenkins-plugin-x.y.z.hpi with x.y.z representing a version number like 2.11.2 in the file selection dialog. Then click the Upload button. Once the plugin has been uploaded to the server, you need to restart your continuous integration server.

17.2.2. Global Configuration

After a successful installation of Nexus IQ for Hudson/Jenkins 1.x, a new option will be available in the Jenkins/Hudson management area, Configure Nexus IQ Plugin. Follow these instructions to configure Jenkins or Hudson to connect to your IQ Server.

figs/web/ci-jenkins-global-config.png

Figure 17.2. Global Configuration of Nexus IQ for Hudson/Jenkins 1.x


IQ Server settings (required)
Server address

This is the address for the IQ Server as it can be reached from the Jenkins/Hudson server. By default, the IQ Server address is http://localhost:8070.

If your IQ Server is behind a proxy server for serving HTTPS or other reasons, you have to use the public URL as it is reachable from the continuous integration server. Only the master Jenkins/Hudson server connects to the IQ Server and you therefore only need to ensure connectivity in terms of open firewall ports and proxy server settings between the master CI server and the IQ Server.

Authentication Method

Select an authentication method:

  1. Select PKI Authentication to delegate authentication to the JVM.
  2. Select User Authentication to specify a username and password:

    1. Username: Enter the username you wish to connect to the IQ Server.

      [Tip]

      Since these settings will be used across all projects for your Jenkins/Hudson installation, we suggest creating a single account on IQ Server, and then associating that account with the Application Evaluator role for the organizations or applications you will be linking to Nexus IQ for Hudson/Jenkins 1.x.

    2. Password: Enter the password for the username entered above.

      [Tip]

      Username and password can also be configured per job.

Global mask options
Anonymize paths
Enabling this feature will anonymize all paths before data is sent to the IQ Server. Ultimately, this prevents the Application Composition Report from reporting the locations/occurrences of components.
Global path options
Scan targets
The scan targets setting allows you to control which files should be examined. The configuration uses an Apache Ant styled pattern, is relative to each project’s workspace root directory, and has a useful default setting that includes all jar, war, ear, zip and tar.gz files. The default value is therefore
**/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz
[Note]

This default only applies if, and only if, neither global nor job config specify scan targets. Adding to this, if you are using a private Maven repository, our default pattern will include your entire Maven repo. This could greatly increase the time necessary for your evaluation, as well as skew evaluation results. To avoid this, consider using a more specialized pattern like **/target/*.jar.

Module excludes
If you are using Sonatype CLM for Maven, you may have noticed the creation of module information files. The process for excluding modules is documented in the Excluding Module Information Files in Continuous Integration Tools section of the Sonatype CLM for Maven chapter.
Advanced options
A number of additional parameters can be supplied to the plugin using this input field. Typically these parameters will be determined by Sonatype support.

17.2.3. Job Configuration

After a completed installation (see Section 17.2.1, “Installation”) and global configuration (see Section 17.2.2, “Global Configuration”) of Nexus IQ for Hudson/Jenkins 1.x, you are ready to configure an invocation as part of a specific job.

Depending on your job type it will be available as a pre and/or post-build step as well as an invocation as a main build step. A pre-build step or a main build step executed before your main build invocation step could be used to examine components existing in the workspace or being placed into the workspace by an earlier build step.

The typical invocation would be as main build step, after the package that should be examined has been created. An example configuration from Jenkins is displayed in Figure 17.3, “Build Scan Configuration for a Build Step”.

figs/web/ci-jenkins-build-scan.png

Figure 17.3. Build Scan Configuration for a Build Step


The configuration options for Nexus IQ for Hudson/Jenkins 1.x invocations mimic the parameters from the global configuration described in Section 17.2.2, “Global Configuration” and are appended to the global parameters. The configuration parameters are:

Optional Job Specific Authentication

While username and password can be configured globally, in some cases you may want a certain job to be associated with a user who has permissions to specific organization and/or applications. Job Specific Authentication allows you to configure a user for this job and use the associated permissions to select the application for the evaluation.

Username
The IQ Server username you wish to use for this job.
Password
The password for the username above.
[Note]

When configuring job specific authentication, please note that global PKI Authentication takes precedence over User Authentication.

Depending on what application is used, the policies associated to the application will be used for the analysis of this build job output. There are two options for choosing what IQ application to associate with the build:

Select an IQ Application
The IQ application dropdown will be populated with the names of applications based on the permissions for the configured user name and password.
Specify an IQ Application
If you want to use a build variable to provide the IQ Application ID, you can enter it in the field displayed after selecting this option. Click on the help icon to the right of the field for information on using build variables (e.g. ${THE_APPLICATION_ID}) to evaluate the application at build time.
Fail the build

Check this option if you want to fail the build when a policy evaluation can’t be performed. Once checked, if for any reason the evaluation is not generated, the build will be failed.

An example of this might be if the IQ Server is inaccessible. In this scenario, the build would fail. In the same example, but where the Fail the build option is left unchecked, the build would be marked unstable.

Stage

This corresponds to the stage you wish the policy evaluation of the application/project to be run against. Additionally, this will correspond to the stage location when viewing report information via the IQ Server (e.g. if you chose the Build stage, summary and dashboard violation results will be displayed accordingly).

[Note]

Depending on how your policies are configured, this may impact warning and fail actions.

Scan targets
The scan targets setting allows you to control which files should be examined with an Apache Ant styled pattern. The pattern is relative to the project workspace root directory and inherits the global configuration.
Module excludes
You can exclude modules from being scanned with module information files configured in this setting. The default value is inherited from the global configuration.
Advanced options
A number of additional parameters can be supplied to the plugin using this input field. Typically these parameters will be recommended to you by the Sonatype support team.