# Scanning Builds

SeaLights build scanner (`sl-build-scanner.jar`) can be used to update `build.gradle` script with the changes needed to run your Gradle build using SeaLights Gradle plugin, similarly as for Maven: [scanning-builds](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-build-tools-plugins/sealights-gradle-plugin/scanning-builds "mention").

{% hint style="warning" %}
Automatic integration of Sealights settings into your *build.gradle* script is currently supported only for **Groovy** language.
{% endhint %}

## Configuration file <a href="#configuration-file" id="configuration-file"></a>

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

1. **token** or **tokenFile** - set with a token or a file containing the token obtained from the SeaLights dashboard
2. Managing the session ID
   1. 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**
   2. If you want to create a Build Session ID using the SeaLights Gradle 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 the scan operation. Note: This is defining a subset, so it must include the star to include all sub-packages/classes
   3. If you want to create a Pull Request Build Session ID using the SeaLights Maven plugin, provide the following fields:
      1. **createPRBuildSessionId** - Set to **true**
      2. **appName** - Name of the application as you want to see it on the SeaLights dashboard
      3. **targetBranch** - The branch to which this PR will be merged (already reported to SeaLights)
      4. **pullRequestNumber** - The number assigned to the Pull Request from the source control
      5. **latestCommit** - The full SHA of the last commit made to the Pull Request
      6. **repositoryUrl** - The pull request URL for the PR to be scanned up until the section before the `pullRequestNumber` value
      7. **packagesIncluded** - Comma-separated list of packages to include in the scan. Note: This is defining a subset, so it must include the asterisk to include all sub-packages/classes
      8. **packagesExcluded** - (Optional) Comma-separated list of packages to include in the scan.  Note: This is defining a subset, so it must include the asterisk to include all sub-packages/classes
3. **executionType** - Provide which executions need to be handled by the Gradle plugin
   1. **full** - Execute both the build scanner and the test listener
   2. **scanonly** - Execute only the build scanner
4. **testTasksAndStages** - (Optional) Mapping of test tasks’ names to test stage names as they will be displayed on the SeaLights dashboard. It should be of the format {"testTask1":"testStage1", "testTask2":"testStage2"}
5. **proxy** - (Optional) Address of proxy to run connection through

{% hint style="info" %}
For additional parameters values and information, see [#installing-test-listener-as-java-agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/java-agent/command-reference#installing-test-listener-as-java-agent "mention") for more parameter values and information
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```javascript
{
  "executionType": "scanonly",
  "tokenFile": "./sltoken.txt",
  "createBuildSessionId": true,
  "appName": "${System.getenv('JOB_NAME')}",
  "branchName": "master",
  "buildName": "${System.getenv('BUILD_NUMBER')}",
  "packagesIncluded": "*com.example.*",
  "packagesExcluded": "",
  "filesIncluded": "*.class",
  "filesExcluded": "*test-classes*",
  "recursive": true,
  "includeResources": true,
  "labId": null,
  "logEnabled": false,
  "logDestination": "console",
  "logLevel": "off",
  "logFolder": "/tmp",
  "gradleProjectConfig": {
    "excludedProjects": ["subProject1", "subProject2"],
    "repoConfig": "mavenLocal()"
  }
}
```

{% endcode %}

{% hint style="info" %}
The values provided for fields can contain interpolated Groovy code, just like for the field `appName` in the above example: `"${System.getenv('JOB_NAME')}"` .\
It will get resolved during the Gradle build.
{% endhint %}

{% hint style="warning" %}

* 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 Gplugin generating automatically a time stamp (yyyy.MM.dd-hh.mm format) as a default buildname
  {% endhint %}

## Integrating into the Build.gradle script <a href="#integrating-into-the-build.gradle-script" id="integrating-into-the-build.gradle-script"></a>

Before running your Gradle build, you run the build scanner with `-gradle` flag to integrate the SeaLights Gradle plugin into the `build.gradle` file. This will create a `sealights.gradle` script with all the configuration taken from the JSON config file and append a reference to it in `build.gradle`.

The standard parameters the build scanner receives are:

* **configfile** - The path to the JSON configuration you created with the parameters to be provided to the SeaLights Gradle plugin
* **workspacepath** - The base path to the location of the `build.gradle` file to update

{% code overflow="wrap" lineNumbers="true" %}

```
java -jar sl-build-scanner.jar -gradle -configfile sl-config.json -workspacepath .
```

{% endcode %}

{% hint style="success" %}
At the successful completion of the command, you’ll see the following last line in the console:\
`[Sealights Build Scanner] - Successfully finished SeaLights integration.`
{% endhint %}

{% hint style="warning" %}
This step will update the root `build.gradle` file and back it up to `build.gradle.slback`copy in the same directory\
If your workspace is not reset for each build, you will need to restore them at the end of the run (see command below).
{% endhint %}

**The next step** is to run your regular Gradle build command, e.g. ‘**gradle clean build’.**

## Restoring the build.gradle file to its previous state <a href="#restoring-the-build.gradle-file-to-its-previous-state" id="restoring-the-build.gradle-file-to-its-previous-state"></a>

If the project is to be restored to its previous state before the SeaLights plugin was applied, use the build scanner with the `-restoreGradle` flag on the workspace where the `gradle.build` file is located:

{% code overflow="wrap" lineNumbers="true" %}

```
java -jar sl-build-scanner.jar -restoreGradle -workspacepath .
```

{% endcode %}

This command will (1) restore `gradle.build` from its backup, (2) delete the backup file, and (3) delete the `sealights.gradle` file. \
Failure at any of these steps won’t prevent the next ones so that the project is restored as much as possible.

## Configuring SCM to enable links from the dashboard <a href="#configuring-scm-to-enable-links-from-the-dashboard" id="configuring-scm-to-enable-links-from-the-dashboard"></a>

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

{% code overflow="wrap" lineNumbers="true" %}

```
"sealightsJvmParams": {
    "sl.scm.provider": "bitbucket",
    "sl.scm.baseUrl": "https://my.bitbucket.com/projects/ABCD/repos/XYZ/browse/A1",
    "sl.scm.version": "4.9.0"
}
```

{% endcode %}

## Pre-downloading the agents <a href="#pre-downloading-the-agents" id="pre-downloading-the-agents"></a>

The Gradle 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`.

{% hint style="info" %}
The agents referred here can be either the latest agent or the recommended one set in your account settings as stated in [downloading-the-java-agent](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/downloading-the-java-agent "mention"). They should be downloaded and made available **prior** to the Gradle execution.
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## Using a local repo <a href="#using-a-local-repo" id="using-a-local-repo"></a>

The Gradle plugin, by default, is downloaded from Maven Central. If you want to update the repo it downloads from, you can do so using the gradleProjectConfig->repoConfig option

{% hint style="info" %}
As repo configurations are usually multiline, its important to maintain this new line format using `\n`
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```
"gradleProjectConfig": {"repoConfig": "maven{\nurl \"https://artifactory.company.com/artifactory/remote-repos\"\ncredentials {\nusername = \"USERNAME\"\npassword = \"PASSWORD\"\n}\n}"}
```

{% endcode %}

## Samples <a href="#samples" id="samples"></a>

### Shell script  <a href="#shell-script" id="shell-script"></a>

This script is very often added to a new pre-build step in your CI configuration (i.e. Jenkins).

{% code overflow="wrap" lineNumbers="true" %}

```sh
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": "${System.getenv(\"JOB_NAME\")}",   
    "branchName": "${System.getenv(\"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": "off",
    "logFolder": "/tmp/sl-logs",
    "scannerJar": "./sl-build-scanner.jar",
    "listenerJar": "./sl-test-listener.jar",
    "sealightsJvmParams": {
      "sl.scm.provider": "bitbucket"
    }
  }' > sl-gradle-build.json
 
echo "Updating Build.gradle with Sealights..."
java -jar sl-build-scanner.jar -gradle -configfile sl-gradle-build.json -workspacepath .
```

{% endcode %}

**Next step** is to run your regular Gradle build command, e.g. **gradle clean build.**

### Gitlab YML <a href="#gitlab-yml" id="gitlab-yml"></a>

{% hint style="info" %}
In the example below:

* Make sure you have defined a `$SEALIGHTS_AGENT_TOKEN` masked variable in your Gitlab settings with a value from your Account’s settings page (Agent Token section).
* You have updated the `packagesincluded` value defined at line 16 to the relevant one form your repository.
  {% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```yaml
build:
  stage: build
  before_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  '{ 
      "executionType":"scanonly",
      "token":"'$SEALIGHTS_AGENT_TOKEN'",
      "createBuildSessionId":true,
      "appName":"'$CI_PROJECT_NAME'",   
      "branchName":"'$CI_COMMIT_BRANCH'", 
      "buildName":"'$CI_PIPELINE_ID - $CI_JOB_STARTED_AT'", 
      "packagesIncluded":"*com.mycompany.*",
      "sealightsJvmParams": {
          "sl.scm.provider": "gitlab",
          "sl.scm.baseUrl": "'${CI_SERVER_URL}/${CI_PROJECT_PATH}'/blob" }
      }' > sl-plugin-settings.json
    - cat sl-plugin-settings.json
    - echo "Updating Gradle with Sealights..."
    - java -jar sl-build-scanner.jar -gradle -configfile sl-plugin-settings.json -workspacepath .
```

{% endcode %}

**The rest of your pipeline is unchanged.**