The SeaLights Pull Request Integration exposes Quality Risks to the developer as part of the Pull Request process, to be displayed and handled before the code is merged into the main branch.

Creating a Personal Access Token on BitBucket

Before making the required configurations on the Bitbucket on-premise installation, a Personal Access Token must be created for authentication with the dedicated SeaLights agent:
- In BitBucket, click on the logged in user and select 'Manage Account'
- On the Left hand side pane, select "Personal access tokens"
- Create a new token to be used to show results in the Bitbucket UI:

→

BitBucket Permissions

The user generating the Personal Access Token must have Read permission for the projects & repositories to be analyzed by Sealights.
It is recommended to define a dedicated user for Sealights from which the PR tasks will be executed.

The application will not modify anything in your repositories and projects as it only requires Read access.

SeaLights Task Runner App Configuration

To report the Pull Request data to SeaLights, the Task Runner must be installed locally on the BitBucket server:
1. Download the Task Runner from the following link: https://s3.amazonaws.com/sl-repo/sl_task_runner/sl_task_runner-2.1.1206.zip
2. Prepare a configuration file to be used by the Task Runner in JSON format:
  - The Bitbucket server properties in this configuration file should be defined within json property "bitbucketServer" as follows:

sl-taskrunner-cfg.json example

{
    "tokenFile": "config/sltoken.txt",
	"bitbucketServer":
        {
            "url": "http://bitbucket.internal.net:7990",
            "token":"<personal access token>"
        }
}

Once the configuration file is created, run the SeaLights task runner .jar file, specifying the configuration file created in the previous step:

Running the SeaLights Task Runner using a configuration file

java -Dsl.config.file=config/sl-taskrunner-cfg.json -jar sl_task_runner.jar

Alternatively, the same parameters can be specified directly as Java params:

Running the SeaLights Task Runner using Java parameters

java -Dsl.tokenFile=/path/to/sltoken.txt -Dsl.bitbucketServer.url=http://bitbucket.internal.net:7990 -Dsl.bitbucketServer.token=<personal access token> -jar sl_task_runner.jar

Common configuration properties for the task runner are as follows:

Property	Default	Required	Description
sl.enableUpgrade	true	optional	Flag allows automatic upgrade
sl.upgradeIntervalMins	1440	optional	Interval in minutes for auto-upgrade version checking
sl.taskPollingIntervalSecs	60	optional	Interval in second for getting SL tasks for execution
sl.taskTimeoutSecs	60	optional	Time in second allocated for task execution; if expires, task will be aborted and reported with timeout status
sl.logs.sendIntervalMin	5	optional	Interval in minutes for sending accumulated logs to the cloud. If not defined, is forced to the default value on start
sl.token	-	mandatory *	The sealights token
sl.tokenFile	-	mandatory *	The file with sealights token
sl.proxy	-	optional	The proxy configuration for connection to Sealights.

Configuring the BitBucket Pull Request to compare data to SeaLights

The pull request job needs to run the SeaLights build scan and test listener for the test stages you want the analysis on.
These results will be compared to the latest build you reported to SeaLights for the branch you are merging the Pull Request to.

Pull Request parameters explanation as seen on a local BitBucket implementation

You can easily identify the relevant values to pass to the Build Scanner based on the illustration below.

Generating a session ID

The difference between the pull request job and standard jobs is in how the session ID is created.
You create the Pull Request build session ID by using the SeaLights Java Build Scanner (See: Downloading the java agent files) with the prConfig option:

prConfig usage

java -jar sl-build-scanner.jar -prConfig {-token <arg> | -tokenfile <arg>} -appname <arg> -targetBranch <arg> -latestCommit <arg> -pullRequestNumber <arg> -repoUrl <arg> [-pi <arg>] [-pe <arg>]

Parameter	Description
token	Access token generated from the SeaLights server
tokenfile	Path to file containing the access token generated from the SeaLights server
appname	The name of the app the Pull Request is being merged to (as provided to SeaLights)
targetBranch	The name of the branch the Pull Request is being merged to (as provided to SeaLights)
latestCommit	The latest commit SHA of the Pull Request branch
pullRequestNumber	The Pull Request number that is being evaluated
repoUrl	The repository URL of the Pull Request and merged branchs
pi, packagesincluded	Comma-separated list of packages to include in scan Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world'
pe,packagesexcluded	Comma-separated list of packages to exclude from scan Supports wildcards (* = any string, ? = any character). For example: 'com.example.* ,io.*.demo, com.?ello.world'
proxy	Address of proxy to run connection through

The packages included and excluded should be exactly the same as what was defined to SeaLights for the merged branch so that the compared results will be the same

Sample of Results on the BitBucket Pull Request page

At the completion of the analysis, Sealights insights will appear at the right hand side of the "Overview" section of your Pull Request.

Clicking on this will open the Quality reports section. Results will appear similar to the one below:

Analyzing a BitBucket Pull Request