Jenkins

As part of our CI/CD integration we provide a native plugin for Jenkins. You can install this plugin from the plugin marketplace directly into your pipeline. The full setup will be done from there. Connecting into your CI/CD pipeline allows developers to utilize existing tooling for their automatic documentation. Instead of tediously open a Web UI after a deployment, they can do all their changes in their IDE - and rely on LeanIX Value Stream Management to capture changes, make them transparent, and notify others.

The data that is synchronized is completely the same as for the generic CI/CD integration. If you, later on, wish to add additional information you can find our customization options here.

Setup

Prerequisites

• The LeanIX plugin must be installed: https://www.jenkins.io/doc/book/managing/plugins/
  *You should have a valid LeanIX API token.
• If you are using scripted pipelines in which the LeanIX plugin is to be integrated as a step, the "Credentials Binding" plugin must be installed: https://plugins.jenkins.io/credentials-binding/
• For freestyle projects, in which the plugin can be added via UI as a build step, the plugin for injecting environment variables might be installed instead: https://plugins.jenkins.io/envinject/
• An SCM provider (e.g. Git) must be configured for the pipeline to be used and the possibly necessary plug-in installed.
• The manifest file made available by LeanIX should be filled with the appropriate values and should be located in the corresponding repository so that it can be accessed by the plugin.

Configuration

The configuration of the LeanIX Plugin is divided into three parts:

• Setting up secrets in the Jenkins administration,
• Central configuration of the plugin,
• Configuration of individual pipelines and jobs in which the plugin is to be used.

Setting up secrets in the Manage Jenkins area.

This section is only important if you want to use the LeanIX plugin in scripted pipelines. For this purpose, a new credentials record with the following parameters is created in Jenkins in the "Manage Jenkins" -> "Security" -> "Manage Credentials" area (a detailed description of how to create credentials can be found at the following link: https:www.jenkins.io/doc/book/using/using-credentials/):

• Scope: It is best to select "global", unless security reasons or company guidelines speak against it.
• Username: The host and thus the part of a URL that specifies the region of the LeanIX service in which the workspace is located, to which the data extracted by the plugin is to be sent (e.g. eu.leanix.net).
• Password: A valid API token for the LeanIX workspace that matches the host.
• ID: "LEANIX_CREDENTIALS" is suggested here, but any valid variable name can be selected. It just needs to be used accordingly in the pipeline.
• Description: No value is needed here.

Central configuration of the plugin

The plugin offers the possibility to centrally configure important settings. After installation, there is an area on the basic level "Dashboard" of Jenkins with the title "LeanIX Value Stream Management" for these configurations.

When you open this page, you will find two areas in which settings can be made.

JSON settings

In the uppermost area with the title "Pipeline Configuration in JSON format" there is an input field in which configurations in JSON format can be inserted.
The structure of these configurations is as follows:

• "leanIXConfigurations" contains all configurations, root of the file
• "deploymentStageVarName": If you use environment variables for the configuration of the stage that your Jenkins job belongs to (e.g. test, production) you can use this field to give the name of the variable and the LeanIX plugin will read out this variable for the information on the stage. The stage can also be set in the local configurations of the jobs.
• "deploymentVersionVarName": If you use environment variables for the configuration of the version of the build that your Jenkins job is running, you can use this field to give the name of the variable and the LeanIX plugin will read out this variable for the information on the version. It is mandatory to give a version, but it can also be given in the local configuration of the jobs.
• "settings": In this array settings for several pipelines can be bundled.
• "pipelines": This array is filled with the names of the pipelines/jobs, for which the following settings should apply
• "path": The path to the LeanIX-manifest-YAML-file in your SCM (Git, SVN etc.) for the pipelines or jobs defined under "pipelines"

For Freestyle projects it is mandatory to add the path to manifest-file here!

This is an example of a configuration:

{
      "leanIXConfigurations": {
        "deploymentStageVarName": "stage",
        "deploymentVersionVarName": "version",
        "settings": [
          {
            "pipelines": [
              "pipeline1",
              "pipeline2",
              "job1"
            ],
            "path": "/other/lx-manifest.yml"
          },
          {
            "pipelines": [
              "pipeline3"
            ],
            "path": "/lx-manifest.yml"
          }
        ]
      }
    }

Job result settings

In the second area, "Job result", you can make the basic setting for all jobs / pipelines, which impact a failure of the LeanIX build step will have for the entire job or the entire pipeline. One of the five options that Jenkins offers, as a result, can be selected here. If the plugin fails, the selected result is set as the end result of the executed job. The default value for the result is "SUCCESS" which means that a failure of the LeanIX-Plugin does not make the pipeline/job fail.

Individual configuration of pipelines and jobs

Configuring Freestyle Projects

To configure a freestyle project, the stage and version of the job must be defined in environment variables. If you have a way to configure this, the name of the variables you use can be set via the central configuration of the plugin, see above. Otherwise the plugin "Environment Injector" (https://plugins.jenkins.io/envinject/) available for Jenkins can be used. The stage and version must be defined in such a way that the names used match those used in the central configuration. In the following example in the central configuration "deploymentStageVarName" was
defined with "stage" and "deploymentVersionVarName" with "version":

In addition, an SCM provider (e.g. Git) must be set up correctly for the project and the LeanIX manifest file must be located there under the path that is specified in the central configuration for this job.

In order to add the LeanIX plugin to the project, a corresponding build step must be created. To do this, click in the configuration of the Freestyle project under "Build" on "Add build step" and select "LeanIX Value Stream Management".

In the input mask with the title "LeanIX Value Stream Management" that then appears, fill in the appropriate values ​​or select from the drop-down menus:

• LeanIX-Manifest-Path -readonly- : This field is readonly, it will be filled automatically after the first run of the plugin. This is the path to the manifest file that is specified in the central configuration. If it is not specified, the default will be "/lx-manifest.yml".
• Hostname: Enter the host name for the appropriate LeanIX region in which your workspace is located.
• Maven-Settings-Path: The path to the settings.xml file in your SCM (Git, SVN etc.) for the pipelines or jobs.
  More details about this attribute is documented under Know How
• Apitoken: Enter the API token that matches the host name or your workspace in this protected field.
• Result in case of failure: Indicate what influence a failure of the LeanIX plugin should have on EXACTLY THIS JOB. If you do not make a selection, the selection of the central configuration is used. If you make a selection, the entry for the central configuration for this job will be overwritten.
• Dependency manager of the SCM: Select which DependencyManager you use for your project. This information is important so that the correct dependencies can be generated from your SCM and integrated into the appropriate factsheet. The LeanIX plugin currently supports NPM, MAVEN and GRADLE.
• Use this LeanIX Build Step: This checkbox indicates whether the LeanIX Build step should be executed or skipped. You can use this to switch it on and off as per job.

Configuring Pipeline projects

In your pipeline definition, the variables for stage and version of the build must be set as environment variables. Define the variable names used in the central configuration (see above), otherwise "stage" is assumed for the stage variable and "version" for the version variable. If you don't have your own way of defining it, you can define these variables in the pipeline as follows:

     environment {
        stage = "dev"
        version = "1.3.0"
    }

Before adding the LeanIX build step to the pipeline, add a secured credentials environment with the Credentials Binding Plugin, as indicated under Prerequisites. The corresponding line looks like this:

     withCredentials ([usernamePassword (credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]{}

• credentialsID: Use the ID that you used in Jenkins, as described under Setting up secrets in the Jenkins administration.

The step in which the LeanIX plug-in is executed must be within the scope of "withCredentials" so that it can securely access the LeanIX API token and the other information.
To configure the LeanIX plugin step you can use the "pipeline Syntax" generator of Jenkins.
A pipeline step with a built-in LeanIX plugin looks like this:

    steps {
        withCredentials([usernamePassword(credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]) {
            leanIXMicroserviceIntelligence hostname: host, useleanixconnector: true, dependencymanager: 'GRADLE'
        }
    }

Usage

When the configuration of the project or pipeline is complete, the start of a build (Build now) will include the execution of the LeanIX plugin. After execution and if the LeanIX plugin step has been reached, there is a menu item called "LeanIX Value Stream Management Log" in the monitoring area of each build (click on the build number in the Pipeline or Project area). In this area you will find the information which values were used for the build by the LeanIX plugin as well as information on the result of the step in the "Status" section. Possible errors will be mentioned here.

The plugin also logs information in the "Console Output" section, which is present with every build.

Options

Fetching dependencies from custom Maven server

📘

Follow Maven official documentation for more details about the settings file

Following is an example maven settings file present in a GitHub repository.

🚧

Ensure to provide the values of id, username, password directly in the file i.e Environment variables cannot be embedded into this during run-time

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>custom-server</id>
            <username>username</username>
            <password>password</password>
        </server>
    </servers>
<!--...-->
</settings>

Following is an example of how to specify the settings.xml file in the LeanIX Value Stream Management build step. Ensure to specify the path relative to the root directory

Following is an example of how to specify the settings.xml file in the pipeline step with a built-in LeanIX plugin. Ensure to specify the path relative to the root directory

steps {
withCredentials([usernamePassword(credentialsId: 'LEANIX_CREDENTIALS', passwordVariable: 'token', usernameVariable: 'host')]) {
leanIXMicroserviceIntelligence hostname: host, useleanixconnector: true, dependencymanager: 'MAVEN', mavensettingspath: './settings.xml'
}
}

🚧

Plugin limitation

In case of failure to read the private dependencies, the plugin currently does not support the feature to only read the public dependencies skipping the private ones.