# Configure Pull Request Flow for SeaLights

This article explains the required steps to report your Pull request to SeaLights, compare it to the merge branch and view the results within your source control.

{% hint style="info" %}
Note that since the results of Pull Request builds are intended to be shown as an overlay within source control using the [chrome-extension-pull-request-integration](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/pull-request-integration/chrome-extension-pull-request-integration "mention"), they are not displayed on the Sealights dashboard
{% endhint %}

The following steps are required to report a Pull Request to SeaLights:

{% stepper %}
{% step %}

### Create a Build Session ID for the Pull Request <a href="#create-a-build-session-id-for-the-pull-request" id="create-a-build-session-id-for-the-pull-request"></a>

You create the Pull Request build session ID by using the SeaLights agent with the **prConfig** option command that requires the following parameters:

<table><thead><tr><th width="174.62890625">Parameter Name</th><th>Description</th></tr></thead><tbody><tr><td>appname</td><td>The same appName reported to SeaLights for this application</td></tr><tr><td>targetBranch</td><td>The branch to which this PR will be merged into (already reported to SeaLights)</td></tr><tr><td>latestCommit</td><td>The full SHA of the last commit made to the Pull Request</td></tr><tr><td>pullRequestNumber</td><td>The number assigned to the Pull Request from the source control</td></tr><tr><td>repoUrl</td><td>The pull request URL for the PR to be scanned, up until the section before the pullRequestNumber value.</td></tr></tbody></table>

The **Target branch must have builds already reported** to Sealights, otherwise the prConfig command will fail.\
If your development process includes pull requests merged to features branch, you may want to exclude them from the scope if Sealights analysis or enforce a build to be reported with the creation of the feature branch (via a webhook).

#### Sample commands <a href="#sample-commands" id="sample-commands"></a>

Below are examples of usage of the prConfig CLI command with the Sealights agents.

{% tabs %}
{% tab title="Java" %}
{% code overflow="wrap" lineNumbers="true" %}

```
java -jar sl-build-scanner.jar -prConfig -tokenfile sltoken.txt -appname "MyAppJava" -targetBranch "master" -latestCommit "$MYGH_PR_COMMIT" -pullRequestNumber "807" -repoUrl "https://www.github.com/myappjava/" -pi "*com.example.*"
```

{% endcode %}
{% endtab %}

{% tab title="slnodejs" %}
{% code overflow="wrap" lineNumbers="true" %}

```
./node_modules/.bin/slnodejs prConfig --tokenfile sltoken.txt --appname "MyAppjs" --pullRequestNumber "448" --targetBranch "develop" --latestCommit $MYGH_PR_COMMIT --repositoryUrl "https://www.github.com/myappjs/" --proxy "http://proxy2.int" 
```

{% endcode %}
{% endtab %}

{% tab title=".Net/Core" %}
{% code overflow="wrap" lineNumbers="true" %}

```
SL.DotNet.exe prConfig --appName "myApp.Net" --pullRequestNumber "770" --targetBranch "develop" --latestCommit $MYGH_PR_COMMIT --repositoryUrl "https://www.github.com/myappdotnet/" --includeNamespace myNameSpace.* --buildSessionIdFile buildSessionId.txt
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" lineNumbers="true" %}

```
sl-python prConfig --tokenfile sltoken.txt --appname "MyApp.py" --targetbranch "main" --pullrequestnumber "123" --latestcommit $MYGH_PR_COMMIT --repourl "https://www.github.com/mypythonapp/" 
```

{% endcode %}
{% endtab %}

{% tab title="Golang (slcli)" %}
{% code overflow="wrap" lineNumbers="true" %}

```
./slcli config create-pr-bsid --app "Myapp.go" --target-branch "main" --pull-request-number "123" --latest-commit $MYGH_PR_COMMIT --repository-url "https://www.github.com/mypgolangapp/"
```

{% endcode %}
{% endtab %}
{% endtabs %}

The parameters packages included for Java and namespace for DotNet should be exactly the same as what was defined to SeaLights for the merged branch so that the compared results will be the same.
{% endstep %}

{% step %}

### Perform a scan and run tests against the PR code <a href="#perform-a-scan-and-run-tests-against-the-pr-code" id="perform-a-scan-and-run-tests-against-the-pr-code"></a>

The same SeaLights flow is then configured within the PR context:

* Using the build session ID created in the previous stage, a complete cycle is run on the PR code:
  * Build scan which includes all modules, including the code changes
  * Test executions assigned to the build are run against the code as part of the PR pipeline

See the following documentation for an example on how to configure this for Maven, using a JSON file: [scanning-builds](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/sealights-maven-plugin/scanning-builds "mention").

{% hint style="info" %}
As Pull Request builds are not reported to the dashboard, in order to to assist with troubleshooting and allow verification that the build was reported successfully to Sealights this job type can be viewed in the Cockpit build monitor. Please note that Pull Request builds are also hidden by default. They can be toggled for viewing under the Settings / Hidden Apps area by searching for the app name and the Pull Request specific branch name format of *SL-\<target branch>-\<pull request number>*
{% endhint %}
{% endstep %}

{% step %}

### Review the results within the PR view in your source control <a href="#review-the-results-within-the-pr-view-in-your-source-control" id="review-the-results-within-the-pr-view-in-your-source-control"></a>

In order to view the results in line

After performing the pull request, you will be able to view the results inline with your source control within the PR view, denoted with a red diamond:

<figure><img src="https://4057366433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjqTCMRYvHhDgsdPLUnc%2Fuploads%2FmOs0XnOl6mGD9vCXgBvI%2Fimage-20200210-145408.png?alt=media&#x26;token=4ed3c86f-a957-47ce-9c3c-c576bdd587a0" alt=""><figcaption></figcaption></figure>

Drilling down into the “Files Changed” tab, will allow you to see the same red diamond annotation in-line with the changed code and a toolbar summarizing Sealights analytics for this build:

<figure><img src="https://4057366433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjqTCMRYvHhDgsdPLUnc%2Fuploads%2FIZdcg1HZEuXBEyN9W1MY%2Fimage-20200210-145730.png?alt=media&#x26;token=28fbd822-bbe0-439b-ad58-a8fb0806c5a9" alt=""><figcaption></figcaption></figure>

<figure><img src="https://4057366433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAjqTCMRYvHhDgsdPLUnc%2Fuploads%2FIqFr0tqhO8AyiigINhex%2Fimage-20200701-061415.png?alt=media&#x26;token=72370e8b-1cba-4c2c-ae06-7c6c1b0ae77d" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### PR Integration with Maven/Gradle plugins  <a href="#pr-integration-with-maven-gradle-plugins" id="pr-integration-with-maven-gradle-plugins"></a>

In case you have configured your “regular builds” to be reported using the JSON configuration for Sealights Maven and/or Gradle plugin, you can include dedicated fields and values to support PR configuration.

The following parameters of the configuration file provide PR integration functionality:

<table><thead><tr><th width="218.55078125">Parameter</th><th width="100.4765625">Type</th><th>Notes</th></tr></thead><tbody><tr><td><strong>createPRBuildSessionId</strong></td><td>boolean </td><td><strong>Mandatory.</strong> Set to true to enable PR integration (Default: false).<br>Cannot be true is the regular createBuildSessionId boolean is also set to true.</td></tr><tr><td><strong>appName</strong> </td><td>String</td><td><strong>Mandatory.</strong> Name of the application as you want to see it on the SeaLights dashboard, must be exactly the same as reported from the regular pipeline builds.</td></tr><tr><td><strong>repositoryUrl</strong></td><td>String </td><td><strong>Mandatory.</strong> The pull request URL for the PR to be scanned, up until the section before the pullRequestNumber value.</td></tr><tr><td><strong>pullRequestNumber</strong></td><td>Number</td><td><strong>Mandatory.</strong> The number assigned to the Pull Request from the source control.</td></tr><tr><td><strong>latestCommit</strong></td><td>String </td><td><strong>Mandatory</strong>. The full SHA of the last commit made to the Pull Request.</td></tr><tr><td><strong>targetBranch</strong></td><td>String </td><td><strong>Mandatory.</strong> The branch to which this PR will be merged into (must be already reported to SeaLights).</td></tr><tr><td><strong>packagesIncluded</strong> </td><td>String</td><td><strong>Mandatory.</strong> Comma-separated list of packages to include in scan</td></tr><tr><td><strong>packagesExcluded</strong> </td><td>String</td><td><strong>Optional</strong> Comma-separated list of packages to include in scan.</td></tr></tbody></table>

#### Sample JSON for Maven/Gradle plugin <a href="#sample-json-for-maven-gradle-plugin" id="sample-json-for-maven-gradle-plugin"></a>

{% hint style="info" %}
In the sample JSON below, please update lines 5 to 10 according to your configuration and project before using it.
{% endhint %}

<pre data-overflow="wrap" data-line-numbers><code><strong>{ 
</strong>    "executionType": "full", 
    "tokenFile": "./sltoken.txt", 
    "createPRBuildSessionId": true,
    "appName": "${JOB_NAME}",   
    "repositoryUrl": "https://www.github.com/${JOB_NAME}",
    "pullRequestNumber": "123",
    "latestCommit": "${MYGH_PR_COMMIT}",
    "targetBranch": "master",
    "packagesIncluded": "*com.example.*",   
    "packagesExcluded": "", 
    "filesIncluded": "*.class", 
    "filesExcluded": "*test-classes*", 
    "recursive": true, 
    "includeResources": true, 
    "testStage": "Unit Tests", 
    "proxy": null,
    "logEnabled": false, 
    "logDestination": "console", 
    "logLevel": "warn",
    "sealightsJvmParams": {}
}
</code></pre>

{% hint style="warning" %}

* If `createPRBuildSessionId` is set to tru&#x65;**,** and at least one of mandatory parameters is not specified, or empty: an error message will be printed and the build will continue without Sealights integration.
* If both `createPRBuildSessionId` and `createBuildSessionId` are both set to `true` - the flow will be ambiguous, so an error message will be printed and the the build will continue without Sealights integration: `"Ambiguous data: createPRBuildSessionId = true and createBuildSessionId=true, cannot create build session id."`
* If `createPRBuildSessionId` is set to false (default value) but PR-specific parameters are provided (`repositoryUrl`, `pullRequestNumber`, `latestCommit`, `targetBranch`) they will be ignored, build will continue as a "regular" one.
  {% endhint %}
  {% endstep %}
  {% endstepper %}

## Related articles <a href="#related-articles" id="related-articles"></a>

* [required-pull-request-parameters-scm-ci](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/pull-request-integration/required-pull-request-parameters-scm-ci "mention")
* [prconfig-command-reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/pull-request-integration/prconfig-command-reference "mention")