Chapter 10.  Integrating with Jenkins

With Jenkins Sonargraph Integration Plugin for Jenkins jobs the findings of Sonargraph can be used to let builds fail, or mark them unstable. Additionally Sonargraph metric values are stored for every build and can be visualized as charts.

10.1. Global Configuration

The first step is to configure one or more versions of Sonargraph Build in "Manage Jenkins""Global Tool Configuration"

10.1.1. Tool Installation for Sonargraph Build

NOTE

This global configuration is only required when you are going to use the "Generate with Sonargraph Build" option in "Sonargraph Integration Generation & Analysis" post-build action.

To see the global configuration options after installing the plugin, go to "Manage Jenkins""Global Tool Configuration" . You will find the "Sonargraph Build" section.

Jenkins - Sonargraph Build Installations
Figure 10.1. Jenkins - Sonargraph Build Installations

Press button "Sonargraph Build Installations..." to see the list of already installed Sonargraph Build installations Jenkins knows about, if any. To add a new "Installation" of Sonargraph Build press button "Add Sonargraph Build", give it a descriptive name, use default Installer "Install from hello2morrow" for it, and select a Sonargraph Build version from the version drop down box.

Jenkins - New Sonargraph Build
Figure 10.2. Jenkins - New Sonargraph Build

NOTE

Version "newest" automatically updates your Sonargraph Build installation to the most recent version.

10.2. Sonargraph License Server

Sonargraph uses a web-based hello2morrow license server for activation code based licenses by default. If you run your own local Sonargraph license server configure it at "Manage Jenkins""Configure System".

Jenkins - License Server Configuration
Figure 10.3. Jenkins - License Server Configuration

10.3. Job Configuration

Use the post-build action "Sonargraph Integration Report Generation & Analysis" to create Sonargraph's XML and HTML reports (or use a pre-generated XML report) and to configure how the Sonargraph analysis should affect the final result of the build. For every Sonargraph metric supported by this plugin, you have the following options:

  • Don't mark: Will not change the build result in any way.

  • Build unstable: If the value for this metric is greater than zero, the build result will be set as "unstable".

  • Build failed: If the value for this metric is greater than zero, the build result will be set as "failure".

Take into account that if you have set to mark the build unstable for one metric, failed for any other and both metric's value are greater than zero, the worst state will prevail, so the build will be marked as failure in this case. Besides controlling the build result, the plugin also generates graphics to monitor the trend of metrics across builds and it will display the full Sonargraph HTML report for each build.

NOTE

For the free Jenkins / SonarQube license, only the options for "cyclic elements" and "empty workspace" are available.

10.3.1. Add post-build action

Add post build action "Sonargraph Integration Report Generation & Analysis" to your job.

Job - Add Post Build Action
Figure 10.4. Job - Add Post Build Action


10.4. Use Pre-Generated Report

Use this option to use a pre-generated Sonargraph report. To do so you must use Sonargraph Maven plugin, Sonargraph Gradle plugin, or Sonargraph Ant task in another upstream build step. Enter the path to the Sonargraph XML report file that has been generated via the ANT task of Sonargraph. This path must be relative to the workspace.

Report - Pre Generated
Figure 10.5. Report - Pre Generated

  • Sonargraph XML Report Enter the path to the pre-generated Sonargraph XML report file (without extension ".xml"). This path must be relative to the workspace.

10.5. Generate Report with Sonargraph Build

Use this option to let Sonargraph Build create a Sonargraph report.

Report - Generate With Sonargraph Build
Figure 10.6. Report - Generate With Sonargraph Build


  • Sonargraph System Directory Enter the path to the Sonargraph system (\*.sonargraph) directory. This path must be relative to the workspace.

  • Sonargraph License File Sonargraph license file location. If this parameter is not specified, you must specify the activation code parameter.

  • Sonargraph Activation Code Sonargraph license activation code. If this parameter is not specified, you must specify a license file parameter.

10.5.1. Advanced Options

Report - Advanced Options
Figure 10.7. Report - Advanced Options

  • Skip Skip Sonargraph Jenkins Plugin.

  • Use Proxy Use Jenkins proxy configuration when connecting to Sonargraph license server.

  • Workspace Profile The profile file name (e.g. "BuildProfile.xml") for transforming the workspace paths to match the build environment.

  • Quality Model File Use a built-in Quality Model, or an external Quality Model instead of the Quality Model included in Sonargraph Software System. Must be either a file within workspace with extension "sgqm", or one of the built-in Quality Models

    • Sonargraph:Default.sgqm (language-independent)

    • Sonargraph:Java.sgqm (language-specific)

    • Sonargraph:CSharp.sgqm (language-specific)

    • Sonargraph:CPlusPlus.sgqm (language-specific)

  • Virtual Model The virtual model to be used when checking for issues. This parameter overrides the default virtual model that is set when the system is opened.

    Licensing:

    • Sonargraph Explorer Changing virtual models is not supported, "Parser" model is taken.

    • Sonargraph Architect Changing virtual models is supported, "Modifiable.vm" is taken by default.

  • Snapshot Directory Target directory for the created snapshot. Only if either this parameter or snapshotFileName is provided, a snapshot will be generated. Parameter can only be used with Sonargraph Architect license.

  • Snapshot File Name The target file name (without extension). Only if either this parameter or snapshotDirectory is provided, a snapshot will be generated. Parameter can only be used with Sonargraph Architect license.

  • Sonargraph Build Version Select the Sonargraph Build version.

  • JDK Select a JDK to be used for Sonargraph Build.

  • Java Select if your Sonargraph system uses Java.

  • C\# Select if your Sonargraph system uses C\#.

  • C++ Select if your Sonargraph system uses C+.

  • Python Select if your Sonargraph system uses Python.

10.5.2. Logging

Job - Logging
Figure 10.8. Job - Logging


  • Log level Level of logging detail. One of: off, error, warn, info, debug, trace, all. Default: info.

  • Log file Path of the log file to be used for SonargraphBuild (relative to workspace of Jenkins job). Default: sonargraph_build.log.

10.5.3. Baseline

Job - Baseline
Figure 10.9. Job - Baseline


  • Baseline Report Path Path to the baseline Sonargraph XML report file (without extension ".xml"). This path must be relative to the workspace.

10.5.4. Chart Configuration

Besides controlling the build result, the plugin also generates graphics to monitor the trend of metrics across builds and it will display the full Sonargraph HTML report for each build.

Job - Chart Configuration
Figure 10.10. Job - Chart Configuration


Either select the charts that you want to show by their language, or show all of them by selecting "All charts".

Job - Select Charts
Figure 10.11. Job - Select Charts


10.5.5. Mark Build

For every Sonargraph metric supported by this plugin, you have the following options:

  • Don't mark: Will not change the build result in any way.

  • Build unstable: If the value for this metric is greater than zero, the build result will be set as "unstable".

  • Build failed: If the value for this metric is greater than zero, the build result will be set as "failure".

Take into account that if you have set to mark the build unstable for one metric, failed for any other and both metric's value are greater than zero, the worst state will prevail, so the build will be marked as failure in this case.

NOTE

For the free Jenkins / SonarQube license, only the options for "cyclic elements" and "empty workspace" are available.

Mark build
Figure 10.12. Mark build


Related topics:

  • See the section about "Workspace Profiles" in the user manual of the standalone application, if the root directories on your build server do not match the workspace definition.

  • Chapter 6, Integrating with Maven

10.6. Configure Jenkins Logging

Sonargraph's Jenkins integration uses the standard Jenkins logger mechanism to provide feedback to the user about the events that occur during the execution of the post-build action or the generation of the graphics. To enable this feature follow these steps:

  • Go to "Manage Jenkins" -> "System Log".

  • Click "Add new log recorder" button.

  • Provide the name you wish for this log recorder.

  • In the field logger, provide the value with the exact value "com.hello2morrow.sonargraph.integration.jenkins" (Without the quotation marks).

  • Select the logging level for this logger.

Now you should have the new log recorder configured like this:

Jenkins - Logging Configuration
Figure 10.13. Jenkins - Logging Configuration


  • Click the save button.

When first created this log recorder is going to be empty and you will be able to see messages as the post-build actions are executed and graphics are generated.