...

...

...

...

...

...

...

...

...

...

...

...

Integrating the SeaLights Maven plugin into your pom.xml

You can use the SeaLights agent to update your maven pom.xml with the needed changes to run your Maven build using the Jenkins Maven Plugin

...

Configuration file

Create a JSON configuration file with the following parameters in order to provide the necessary configuration fields to the SeaLights Maven plugin:

1. configuration section with the following parameters
   1. token or tokenFile - set with a token or a file containing the token obtained from the SeaLights dashboard
   2. If you create a Build Session ID externally, provide the following fields:
      
      1. buildSessionId or buildSessionIdFile - Set with a build session id or a file containing the build session id created by the config step
      2. createBuildSessionId - Set to false
         
   3. If you want to create a Build Session ID using the SeaLights Maven plugin, provide the following fields:
      1. createBuildSessionId - Set to true
      2. appName - Name of the application as you want to see it on the SeaLights dashboard
      3. branchName - Name of the branch as you want to see it on the SeaLights dashboard
      4. buildName - Name of the build as you want to see it on the SeaLights dashboard
      5. packagesIncluded - Comma-separated list of packages to include in scan. Note: This is defining a subset, so it must include the astrix to include all sub packages/classes
      6. packagesExcluded - (Optional) Comma-separated list of packages to include in scan.  Note: This is defining a subset, so it must include the astrix to include all sub packages/classes
   4. executionType - Provide which executions need to handled by the Maven plugin
      1. full - Execute both the build scanner and the test listener
      2. testsonly - Execute only the test listener
      3. scanonly - Execute only the build scanner
   5. filesincluded - (Optional) Set to the binary files to scan. Default: *.class
   6. filesexcluded - (Optional) Set to the binary files to excluded from the scan. Default:*test-classes*
      
   7. workspacepath - Set to with the path to the binary files to scan (Different per module). Default: ${project.build.outputDirectory}
      Note: there are rare cases that this needs to be changed. Make sure you really need to change it before doing so.
   8. moduleNameArtifactId - (Optional) Set to true to set automatically the module name for each sub-project to be based on ${project.artifactId}. Default: false.
   9. recursive - (Optional) Set to true to scan all the subdirectories of workspacepath. Default: true
   10. includeResources - (Optional) Set to include the token and build session ID files in the built resources
   11. testStage - (Optional) Set the name of the test stage as will be displayed on the SeaLights dashboard
   12. labId - (Optional) Unique ID for a set of test labs in case multiple labs are running simultaneously
   13. filesStorage - Set to the temp folder for the agent to create temporary files in. For example /tmp
   14. logEnabled - Set to true if you want a log to be created
   15. logLevel - Set the log level to create. For example INFO
   16. proxy - (Optional) Address of proxy to run connection through
   17. sealightsJvmParams - Entry to provide JVM params to the SeaLights agent. It should be of the format {"key1":"val1", "key2":"val2"}
   18. metadata section with CI details
       
       1. jobName - Set to the name of the build job. For example ${JOB_NAME}
       2. logsUrl - Set to the link that the SeaLights dashboard should provide to view the build log. For example ${BUILD_URL}/console
   19. enabled - (Optional) Set to false to disable SeaLights agent. Default: true.

{
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${JOB_NAME}",
  "branchName": "master",
  "buildName": "${BUILD_NUMBER}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "testStage": "Unit Tests",
  "labId": null,
  "executionType": "full",
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "off",
  "logFolder": "/tmp",
  "sealightsJvmParams": {},
  "enabled": true
}

Configuring SCM 

SeaLights by default provides all links to the SCM for Github.

You can configure SeaLights to prepare the links for Bitbucket and Gitlab as well with the following parameters placed under the sealightsJvmParams section:

• sl.scm.provider - set to github, bitbucket or gitlab
• sl.scm.baseUrl - When working with an on-premise installation of your SCM and access from the build machine is different than the one accessed by the users, then you can provide the base URL to use
• sl.scm.version - set to the version of the on-premise version you use

  "sealightsJvmParams": {
    "sl.scm.provider": "bitbucket",
    "sl.scm.baseUrl": "https://{dns}/projects/{project}/repos/{repo}/browse",
    "sl.scm.version": "4.9.0"
}

...

If your on premise SCM version is often updated in order to comply with latest security patches for example, you can also provide a version retrieved dynamically as the sample command lines below

...

Integrating the SeaLights Maven plugin into your pom.xml

You can use the SeaLights agent to update your maven pom.xml with the needed changes to run your Maven build using the Jenkins Maven Plugin

Configuration file

Create a JSON configuration file with the following parameters in order to provide the necessary configuration fields to the SeaLights Maven plugin:

1. configuration section with the following parameters

   1. token or tokenFile - set with a token or a file containing the token obtained from the SeaLights dashboard

   2. If you create a Build Session ID externally, provide the following fields:

      1. buildSessionId or buildSessionIdFile - Set with a build session id or a file containing the build session id created by the config step

      2. createBuildSessionId - Set to false

   3. If you want to create a Build Session ID using the SeaLights Maven plugin, provide the following fields:

      1. createBuildSessionId - Set to true

      2. appName - Name of the application as you want to see it on the SeaLights dashboard

      3. branchName - Name of the branch as you want to see it on the SeaLights dashboard

      4. buildName - Name of the build as you want to see it on the SeaLights dashboard

      5. packagesIncluded - Comma-separated list of packages to include in scan. Note: This is defining a subset, so it must include the asterisk to include all sub packages/classes

      6. packagesExcluded - (Optional) Comma-separated list of packages to include in scan.  Note: This is defining a subset, so it must include the asterisk to include all sub packages/classes

   4. executionType - Provide which executions need to handled by the Maven plugin

      1. full - Execute both the build scanner and the test listener

      2. testsonly - Execute only the test listener

      3. scanonly - Execute only the build scanner

   5. filesincluded - (Optional) Set to the binary files to scan. Default: *.class

   6. filesexcluded - (Optional) Set to the binary files to excluded from the scan. Default:*test-classes*

   7. workspacepath - Set to with the path to the binary files to scan (Different per module). Default: ${project.build.outputDirectory}
      Note: there are rare cases that this needs to be changed. Make sure you really need to change it before doing so.

   8. moduleNameArtifactId - (Optional) Set to true to set automatically the module name for each sub-project to be based on ${project.artifactId}. Default: false.

   9. recursive - (Optional) Set to true to scan all the subdirectories of workspacepath. Default: true

   10. includeResources - (Optional) Set to include the token and build session ID files in the built resources

   11. testStage - (Optional) Set the name of the test stage as will be displayed on the SeaLights dashboard

   12. labId - (Optional) Unique ID for a set of test labs in case multiple labs are running simultaneously

   13. filesStorage - Set to the temp folder for the agent to create temporary files in. For example: /tmp or C:\\Temp

   14. logEnabled - Set to true if you want a log to be created

   15. logLevel - Set the log level to create. For example: INFO

   16. proxy - (Optional) Address of proxy to run connection through

   17. sealightsJvmParams - Entry to provide JVM params to the SeaLights agent. It should be of the format {"key1":"val1", "key2":"val2"}

   18. metadata section with CI details

       1. jobName - Set to the name of the build job. For example: ${JOB_NAME}

       2. logsUrl - Set to the link that the SeaLights dashboard should provide to view the build log. For example: ${BUILD_URL}/console

   19. enabled - (Optional) Set to false to disable SeaLights agent. Default: true.

Sample of 'sealights' profile

{
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${JOB_NAME}",
  "branchName": "master",
  "buildName": "${BUILD_NUMBER}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "testStage": "Unit Tests",
  "labId": null,
  "executionType": "full",
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "off",
  "logFolder": "/tmp",
  "sealightsJvmParams": {},
  "enabled": true
}

Configuring SCM 

SeaLights by default provides all links to the SCM for Github.

You can configure SeaLights to prepare the links for Bitbucket and Gitlab as well with the following parameters placed under the sealightsJvmParams section:

• sl.scm.provider - set to github, bitbucket or gitlab

• sl.scm.baseUrl - When working with an on-premise installation of your SCM and access from the build machine is different than the one accessed by the users, then you can provide the base URL to use

• sl.scm.version - set to the version of the on-premise version you use

Sample of SCM Parameters

  "sealightsJvmParams": {
    "sl.scm.provider": "bitbucket",
    "sl.scm.baseUrl": "https://{dns}/projects/{project}/repos/{repo}/browse",
    "sl.scm.version": "4.9.0"
}

Surefire and Failsafe argLine update

If you have configured the argLine for surefire and/or failsafe, the integration will include adding @{sealightsArgLine} to them.
This can be updated/overridden by adding and updating the following parameters to the json JSON file:

• surefireArgLine - Whatever is defined here will be updated in the argLine of surefire if it exists. By default

  '

  @{sealightsArgLine}

  '

• failsafeArgLine - Whatever is defined here will be updated in the argLine of failsafe if it exists. By default

  '

  @{sealightsArgLine} -Dsl.testStage="Integration Tests"

  '

...

Sample of Surefire and Failsafe argLine update

"surefireArgLine": "-Xms1280m -Xmx1280m @{sealightsArgLine}"
"failsafeArgLine": "-Xmx8192m @{sealightsArgLine} -Dsl.testStage=\"Integration Tests\""

...

You can add tags to be viewed in the cockpit for the agents started by this maven job by passing them through the sl.tags property in the sealightsJvmParams the sealightsJvmParams field

"sealightsJvmParams": {
    "sl.tags": "mytag",
}

...

The Maven plugin downloads the recommended agent at the beginning of the run. If you want to pre-download them and provide them to the plugin, you can do so with the flags scannerJar & listenerJar.

"scannerJar": "./sl-build-scanner.jar"
"listenerJar": "./sl-test-listener.jar"

Integrating into the pom.xml files

Before running your maven build, you run the build scanner with -pom flag to integrate the SeaLights Maven Plugin into the pom.xml files.

The parameters it receives are:

...

• configfile - The path to the JSON configuration you created with the parameters to be provided to the SeaLights Maven Plugin

• pluginversion - The version of the Maven SeaLights Plugin to insert into the pom.xml

• workspacepath - The base path to the location of the pom.xml files to update

...

Sample Command

java -jar sl-build-scanner.jar -pom -configfile slmaven.json -workspacepath .

...

In case the pom file is to be restored to its previous state before the Sealights plugin was applied, use the build scanner with the -restore flag on the workspace where the pom.xml file is located:

java -jar sl-build-scanner.jar -restorePom -workspacepath .

Sample script 

echo "Downloading Sealights Agents..."
wget -nv https://agents.sealights.co/sealights-java/sealights-java-latest.zip
unzip -o sealights-java-latest.zip
echo "Sealights agent version used is:" `cat sealights-java-version.txt`

echo  '{ 
    "tokenFile": "./sltoken.txt", 
    "createBuildSessionId": true,
    "appName": "${JOB_NAME}",   
    "branchName": "${GIT_BRANCH}", 
    "buildName": "${BUILD_NUMBER}",  
    "packagesIncluded": "*com.example.*",   
    "packagesExcluded": "", 
    "filesIncluded": "*.class", 
    "filesExcluded": "*test-classes*", 
    "recursive": true, 
    "includeResources": true, 
    "testStage": "Unit Tests", 
    "labId": null, 
    "executionType": "full", 
    "logEnabled": false, 
    "logDestination": "console", 
    "logLevel": "warn", 
    "logFolder": "/tmp", 
    "sealightsJvmParams": {}, 
    "enabled": true, 
    "filesStorage": "/tmp"
  }' > slmaven.json
 
echo "Updating POM with Sealights..."
java -jar sl-build-scanner.jar -pom -configfile slmaven.json -workspacepath .

...