Sonargraph Integration

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

• Stored XSS vulnerability

This plugin integrates Sonargraph version 9 and newer into your build. Sonargraph allows to define an architecture for a software system and automatically checks how the code base conforms to it.

Sonargraph analyzes the static (i.e. compile-time) dependencies of your software. The free-of-charge license for the integration with Jenkins and also SonarQube allows to detect cyclic dependencies and additional metrics. You can mark the build as "unstable" or "failed" if cyclic dependencies are detected.
The real benefit of Sonargraph is that you can define a logical architecture and perform automatic checks how the code conforms to it. This functionality is only available for free, if you are working on a non-commercial Open-Source project. More information is available on our homepage, you can check there if you are eligible for a free license.

The Sonargraph Build component integrates Sonargraph in Ant, Bazel, Gradle, Maven and Shell based builds. The online manual provides more details. This Jenkins plugin allows to define if the build should be marked as "unstable" or "failed" if architecture violations, cyclic dependencies, etc. are detected. Trends of metrics are displayed in charts and additionally the generated detailed HTML report is available for each build.

If you already have Sonargraph integrated in your build, and a Sonargraph report is already generated during one of your build steps, use the post-build step called "Sonargraph Integration Report Generation & Analysis", and select "Pre-generated". In this case no global Jenkins configuration for Sonargraph Build is needed.

If you are new to Sonargraph, we advice you to register on our Sonargraph Web Site, have a look at the whitepapers and screencasts to get an idea of Sonargraph's capabilities.
You need to have a license in order to analyse a project. To get started an evaluation license or the free integration license is sufficient.

If you are new to Sonargraph, use the post-build step called "Sonargraph Integration Report Generation & Analysis", and select "Generate with Sonargraph Build". In this case an installation of SonargraphBuild must be configured in global Jenkins configuration.

NOTE: This Jenkins plugin requires Sonargraph version 9 and newer. For Sonargraph version 7 use Sonargraph Plugin.

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

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

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.

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

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

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.

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

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.

• "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.

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

• "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.

• "Skip" Skip Sonargraph Jenkins Plugin.
• "UseProxy" 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.

• "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.

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

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.

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

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.

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:

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

• Fixed Issue Category 'QualityGate'

• Requires Sonargraph Build 10.4.0

• Added possibility to mark build on quality gate issues

• Moved documentation from wiki to github

• Pipeline support
• Use Jenkins Proxy settings for SonargraphBuild’s license handler
• Added links for Sonargraph diff reports
• Removed splitting options

• Security fix SECURITY-1775

• Sonargraph baseline report support
• Java 11 support

• Fixed misleading message regarding Cycle Groups
• Fixed link "Show most recent Sonargraph Report"
• Show basic progress info for SonargraphBuild 9.12.0

• Support for Sonargraph Python systems
• No metadata file needed anymore to get dynamic metrics created by automated Sonargraph scripts
• Select charts by language
• Requires SonargraphBuild 9.9.2

• Fixed problem on Jenkins/Java/SonargraphBuild installation directories containing blanks

• Requires SonargraphBuild 9.4.6

• Requires SonargraphBuild 9.4.3

• Fixed Sonargraph Charts on slave

• Support for Sonargraph License Server
• Support for splitting of large Sonargraph Reports

• Support for new Sonargraph Report format
• Requires SonargraphBuild 9.1.1

• Fixed "Pre-Generated" on slave
• Fixed "Generate with Sonargraph Build" on slave
• Fixed report history for "Pre-Generated" when report name was changed from default

• Added configuration parameter "logLevel" (ironiusn)
• Set build result "failed" instead of "aborted" if report is missing (patrickschlebusch)
• Added configuration parameter "logFile"
• Updated default meta data file
• Read changed meta data file immediately

Plugin version 5.0.0: Compatible with SonargraphBuild >= 10.4.0 and Jenkins >= 2.222.4

Plugin version 4.0.0: Compatible with SonargraphBuild >= 9.9.2 and Jenkins >= 2.222.3

Plugin version 3.0.0: Compatible with SonargraphBuild >= 9.9.2 and Jenkins >= 2.164.3

Plugin version 2.2.0: Compatible with SonargraphBuild >= 9.9.2 and Jenkins >= 2.138.2

Plugin version 2.1.1: Compatible with SonargraphBuild >= 9.4.6 and Jenkins >= 1.609.3

Plugin version 2.1.0: Compatible with SonargraphBuild >= 9.4.3 and Jenkins >= 1.609.3

Plugin version 2.0.0: Compatible with SonargraphBuild 9.1.1 - 9.4.2 and Jenkins >= 1.609.3

Plugin version 1.1.4: Compatible with SonargraphBuild 8.x - 9.1.0 and Jenkins >= 1.609.3