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
Agent Files
There are two agent files
Build Scanner - sl-build-scanner.jar
Test Listener - sl-test-listener.jar
Download them from: https://agents.sealights.co/sealights-java/sealights-java-latest.zip
Configuration file
JSON configuration parameters reference
Create a JSON configuration file with the following parameters in order to provide the necessary configuration fields to the SeaLights Maven plugin:
configuration section with the following parameters
token or tokenFile - set with a token or a file containing the token obtained from the SeaLights dashboard
If you create a Build Session ID externally, provide the following fields:
buildSessionId or buildSessionIdFile - Set with a build session id or a file containing the build session id created by the config step
createBuildSessionId - Set to false
If you want to create a Build Session ID using the SeaLights Maven plugin, provide the following fields:
createBuildSessionId - Set to true
appName - Name of the application as you want to see it on the SeaLights dashboard
branchName - Name of the branch as you want to see it on the SeaLights dashboard
buildName - Name of the build as you want to see it on the SeaLights dashboard
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
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
If you want to create a Pull Request Build Session ID using the SeaLights Maven plugin, provide the following fields:
createPRBuildSessionId - Set to true
appName - Name of the application as you want to see it on the SeaLights dashboard
targetBranch - The branch to which this PR will be merged into (already reported to SeaLights)
pullRequestNumber - The number assigned to the Pull Request from the source control
latestCommit - The full SHA of the last commit made to the Pull Request
repositoryUrl - The pull request URL for the PR to be scanned, up until the section before the pullRequestNumber value
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
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
executionType - Provide which executions need to handled by the Maven plugin
full - Execute both the build scanner and the test listener
testsonly - Execute only the test listener
scanonly - Execute only the build scanner
filesincluded - (Optional) Set to the binary files to scan. Default:
*.class
filesexcluded - (Optional) Set to the binary files to excluded from the scan. Default:
*test-classes*
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.moduleNameArtifactId - (Optional) Set to true to set automatically the module name for each sub-project to be based on
${project.artifactId}
. Default: false.recursive - (Optional) Set to true to scan all the subdirectories of workspacepath. Default:
true
includeResources - (Optional) Set to include the token and build session ID files in the built resources
testStage - (Optional) Set the name of the test stage as will be displayed on the SeaLights dashboard
labId - (Optional) Unique ID for a set of test labs in case multiple labs are running simultaneously
filesStorage - Set to the temp folder for the agent to create temporary files in. For example:
/tmp
orC:\\Temp
logEnabled - Set to true if you want a log to be created
logLevel - Set the log level to create. For example:
INFO
proxy - (Optional) Address of proxy to run connection through
sealightsJvmParams - Entry to provide JVM params to the SeaLights agent. It should be of the format
{"key1":"val1", "key2":"val2"}
metadata section with CI details
jobName - Set to the name of the build job. For example:
${JOB_NAME}
logsUrl - Set to the link that the SeaLights dashboard should provide to view the build log. For example:
${BUILD_URL}/console
If you override the surefire <argLine>...</argLine> then you need to add the SeaLights parameters inside the override value. See Surefire integration
Do not call the JSON file 'sealights.json' as the agent uses this file name for override options
For troubleshooting purpose, you can use
"buildName":"SL_Timestamp"
in your JSON file to have the Sealights Maven plugin generating automatically a time stamp (yyyy.MM.dd-hh.mm
format) as a default build name.
See 'Java Command Reference - Installing test listener as Java Agent' for more parameter values and information
Sample of 'sealights' profile
{ "executionType": "full", "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", "logEnabled": false, "logDestination": "console", "logLevel": "off", "logFolder": "/tmp", "sealightsJvmParams": {} }
Frequently used parameters
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" }
For more details and recommendations on how to set those 3 parameters, please refer to our dedicated page https://sealights.atlassian.net/l/c/300TDd3Y .
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 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\""
Tagging
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
field
"sealightsJvmParams": { "sl.tags": "mytag", }
Pre-downloading the agents
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"
The agents used here should be downloaded either with the latest agent or the recommended one as stated in Downloading the java agent files
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 .
This step will update all the pom.xml
files and back them up to pom.xml.slback
You will need to restore them at the end of the run if you do not reset your workspace.
Restoring the pom.xml file to its previous state
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
Best Practice: This script is very often added to a dedicated pre-build step in the CI job (i.e. Jenkins).
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 '{ "executionType": "scanonly", "tokenFile": "./sltoken.txt", "createBuildSessionId": true, "appName": "${JOB_NAME}", "branchName": "${GIT_BRANCH}", "buildName": "SL_Timestamp", "packagesIncluded": "*com.example.*", "packagesExcluded": "", "filesIncluded": "*.class", "filesExcluded": "*test-classes*", "recursive": true, "includeResources": true, "proxy": null, "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 .
Next step is to run your regular maven command typicall like 'mvn clean install' or 'mvn clean verify' for example.