# ALTERNATIVE: Gradle Plugin

{% hint style="warning" %}
**Prerequisite:** You have completed [Phase 2: Advanced Coverage Analytics](https://docs.sealights.io/knowledgebase/phased-onboarding/java-onboarding-guide/phase-2-advanced-coverage-analytics)
{% endhint %}

The **SeaLights Gradle plugin** is designed to wrap the entire process (Build Scan + Test Listener functions) into the Gradle lifecycle, allowing **seamless integration with the build tool**.

In this ALTERNATIVE approach (to [integrating SeaLights into your CI](https://docs.sealights.io/knowledgebase/phased-onboarding/java-onboarding-guide/phase-3-continuous-coverage)), the SeaLights build scanner (`sl-build-scanner.jar`) is used to update `build.gradle` script with the changes needed to run your Gradle build using SeaLights Gradle plugin,

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

## Implementation Steps

{% hint style="info" %}
Prerequisite: Your application is already set up to run with SeaLights as a `javaagent`, per the instructions in previous phases.
{% endhint %}

{% stepper %}
{% step %}

#### Download the SeaLights Java Agent

{% hint style="info" %}
You have previously downloaded the SeaLights Java agent for use by your component at runtime (adding it as a `javaagent` in Phase 1), and on your Test Runners (Phase 2). Now you will need the SeaLights Java Agent to be available during the build step in your CI pipeline.
{% endhint %}

Download the latest version of the SeaLights Java Agent. 

There are two agent files

* Build Scanner - sl-build-scanner.jar
* Test Listener - sl-test-listener.jar

These agent files can be downloaded from: <https://agents.sealights.co/sealights-java/sealights-java-latest.zip>

Example CLI commands for downloading the SeaLights Java Agent:

```bash
# Download the latest Java agent
wget -nv https://agents.sealights.co/sealights-java/sealights-java-latest.zip

# Extract the agent
unzip -oq sealights-java-latest.zip
```

{% hint style="info" %}
Instructions for downloading a specific version of the agent can be found [here](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/downloading-the-java-agent#downloading-the-specific-agent-version-defined-in-customer-settings)
{% endhint %}

{% hint style="info" %}
Note: You will also need a valid SeaLights Agent Token, as explained in the [prerequisites](https://docs.sealights.io/knowledgebase/phased-onboarding/java-onboarding-guide/getting-started/prerequisites "mention")
{% endhint %}
{% endstep %}

{% step %}

#### Create a configuration file

This step allows you to set any necessary configuration in a dedicated configuration file, which will be used when adding the SeaLights Maven Plugin details to your project's `pom.xml`

**Minimum Required Parameters for this configuration:**

* `tokenfile` - Path to the [**agent token file**](https://docs.sealights.io/knowledgebase/phased-onboarding/getting-started/prerequisites#access-credentials). Note: The token can also be placed in a file named `sltoken.txt` in the same directory as the agent. In that case, this parameter is not required.
* `appname` - The **name of your component**. This name will appear in the SeaLights dashboard and reports. This can be any name that represents your component.
* `branchname` - Git branch name (defaults to "main" if not specified)
* `buildname` - A **unique identifier** that represents the current build of your component — for example, the CI build number, a timestamp, or a custom name (as long as it is unique).
* `packagesIncluded` - A comma-separated list of packages composing the application. Specifies which Java packages SeaLights should monitor for coverage. By default, SeaLights may analyze all packages, but explicitly setting this improves performance.
* `createBuildSessionId` - Set to true

Additional Recommended Parameters:

* `includeResources` - Set to **true** to package your buildsessionid.txt and sltoken.txt into your build artifact

**Example Configuration File:**

{% code overflow="wrap" %}

```json
{
  "executionType": "full",
  "tokenFile": "sltoken.txt",
  "createBuildSessionId": true,
  "appName": "<component-name>",
  "branchName": "<branch-name>",
  "buildName": "<build-name>",
  "packagesIncluded": "*com.example.*",
  "includeResources": true,
  "sealightsJvmParams": {}
}
```

{% endcode %}

Additional optional parameters may be found here: [java-plugin-configuration-parameters](https://docs.sealights.io/knowledgebase/phased-onboarding/java-agent-parameter-reference/java-agent-configuration-parameters/java-plugin-configuration-parameters "mention")

{% hint style="warning" %}
Do NOT name this configuration file `sealights.json` as this is a reserved file name used by the agent for internal override options.
{% endhint %}
{% endstep %}

{% step %}

#### Add the plugin to your build.gradle

This step adds the SeaLights Gradle plugin, configured with the items specified in your config file, to your project's `build.gradle` . To accomplish this, you will use the command `java -jar sl-build-scanner.jar -gradle -configfile <config-file-name> [options]`

By doing this, you allow the SeaLights Gradle plugin to add the necessary SeaLights configuration to automatically complete the configuration, BSID generation, and build scan (steps 2-3 if you were using the implementation steps from [#implementation-steps](https://docs.sealights.io/knowledgebase/phased-onboarding/java-onboarding-guide/phase-3-continuous-coverage/..#implementation-steps "mention")) as a part of your Gradle build.

**Minimum Required Parameters for this command:**

* `-configFile` - Path to the file containing the JSON configuration you created in Step 2.
* `-workspacepath` - The base path to the location of the pom.xml files to update

**Command:**

```bash
java -jar sl-build-scanner.jar -gradle -configfile <config-file-name> -workspacepath .
```

What this command does:

* Updates your `build.gradle` with the SeaLights Gradle plugin and configuration details.&#x20;
* Creates a backup of your original `build.gradle` named `build.gradle.slback`

**Output:** In the console, you will see `[Sealights Build Scanner] - Successfully finished SeaLights integration`  if the command was successful.

{% endstep %}

{% step %}

#### Build your artifact

The next step is to simply build your artifact as you normally would (typically with something like `gradle clean build` ).&#x20;

The SeaLights Gradle plugin was added to your `build.gradle` file, so when you run your build, it is automatically packaged up as part of your artifact.&#x20;

When this build is deployed, the JVM changes you completed during Phase 1 will take effect and your artifact will be deployed with the SeaLights agent attached as a `-javaagent`
{% endstep %}

{% step %}

#### Restore your pom.xml (Optional)

{% hint style="warning" %}
IF your workspace is not reset for each run, you will need to restore them at the end of the run&#x20;
{% endhint %}

Use the `-restoreGradle` flag to restore your pom.xml to its original content.

Command:

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

{% endstep %}
{% endstepper %}

## Verification

To confirm that Phase 3 was successful:

1. **Check the console output** — Look for messages confirming successful agent startup and scan completion.
2. Visit the SeaLights Dashboard — Verify that:
   1. Your component's build name appears with the name you have given it in the configuration file
   2. Coverage data is correctly reflected in the test stage

***

## Next Steps

With Continuous Coverage in your CI now in place, you can move to [**Phase 4: Test Impact Analysis**](https://docs.sealights.io/knowledgebase/phased-onboarding/java-onboarding-guide/phase-4-test-impact-analysis-tia). In Phase 4, you'll begin using TIA to execute the smallest subset of tests — without compromising quality.