> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md).

# Generating a Session ID

Create a build session ID with slnodejs config (or prConfig for pull request builds) and pass it to the later commands of the same build.

A build session ID identifies one build of an application. Create it once per build, before the scan, and pass the same ID to every later command of that build (scan, runtime coverage, tests), so SeaLights links them as one cycle.

{% hint style="info" %}
You need an agent token. See [Generating an Agent token](https://docs.sealights.io/knowledgebase/settings/token-access-and-management#token-list-and-token-creation-2) and [Configuration → Token](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#token).
{% endhint %}

## Create the build session ID <a href="#generating-a-session-id-in-node.js" id="generating-a-session-id-in-node.js"></a>

`config` creates the build session and writes its ID to the file `buildSessionId` in the working directory (or to the file you pass with `--buildSessionIdFile`).

{% tabs %}
{% tab title="Bash" %}

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs config \
  --tokenFile sltoken.txt \
  --appName "my-app" \
  --branchName "main" \
  --buildName "$(date -u +%Y%m%d_%H%M%S)"
cat buildSessionId
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Set-Content -Path sltoken.txt -Value $env:SEALIGHTS_AGENT_TOKEN -NoNewline
npx slnodejs config `
  --tokenFile sltoken.txt `
  --appName "my-app" `
  --branchName "main" `
  --buildName (Get-Date -Format "yyyyMMdd_HHmmss")
Get-Content buildSessionId
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: Create SeaLights build session
  env:
    SEALIGHTS_AGENT_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
  run: |
    printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
    npx slnodejs config \
      --tokenFile sltoken.txt \
      --appName "${{ github.event.repository.name }}" \
      --branchName "${{ github.ref_name }}" \
      --buildName "${{ github.run_id }}-${{ github.run_attempt }}"
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
    npx slnodejs config \
      --tokenFile sltoken.txt \
      --appName "$(Build.Repository.Name)" \
      --branchName "$(Build.SourceBranchName)" \
      --buildName "$(Build.BuildId)"
  displayName: Create SeaLights build session
  env:
    SEALIGHTS_AGENT_TOKEN: $(SEALIGHTS_AGENT_TOKEN)
```

{% endtab %}
{% endtabs %}

### Naming rules <a href="#naming-rules" id="naming-rules"></a>

| Flag           | Rule                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--appName`    | Stable for the application across builds and branches. Case-sensitive.                                                                                                    |
| `--branchName` | The source branch. Case-sensitive.                                                                                                                                        |
| `--buildName`  | **Unique** for every build of the application and branch. Use the CI build number, the run ID plus attempt, or the commit SHA plus a timestamp. Locally, use a timestamp. |

{% hint style="warning" %}
Reusing a `buildName` is the most common cause of the `Module already exists` error.
{% endhint %}

Optional: `--beControlledVersions` installs the `slnodejs` version that SeaLights recommends for your account before creating the session. See [`config` in the Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#config).

## Use the build session ID in later commands <a href="#using-the-session-id" id="using-the-session-id"></a>

Pass the ID to every later command, in one of these ways:

| Method               | Example                                            | When to use                                                                                                                                                                                             |
| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File (default)       | `--buildSessionIdFile buildSessionId`              | Same job, or keep the file as a CI artifact for later jobs. `scan`, `instrument`, `mocha`, `run`, `uploadReports` and `nycReport` read `buildSessionId` in the working directory even without the flag. |
| Value                | `--buildSessionId "$SL_BSID"`                      | Pass the ID between jobs or pipelines as a variable.                                                                                                                                                    |
| Environment variable | `export SL_buildSessionId="$(cat buildSessionId)"` | CLI commands read `SL_buildSessionId` (case-sensitive). The preload script also reads `SL_BUILD_SESSION_ID`.                                                                                            |

{% hint style="warning" %}
CLI commands do not read `SL_BUILD_SESSION_ID` (upper case); only the preload script does. For CLI commands, use `--buildSessionId`, `--buildSessionIdFile`, or `SL_buildSessionId`.
{% endhint %}

Passing the ID to a later job:

{% tabs %}
{% tab title="GitHub Actions" %}

```yaml
- name: Keep the build session ID
  run: echo "SL_BSID=$(cat buildSessionId)" >> "$GITHUB_ENV"
- name: Scan
  run: npx slnodejs scan --tokenFile sltoken.txt --buildSessionId "$SL_BSID" --scanDir dist --scmType git
```

For a later job, upload `buildSessionId` with `actions/upload-artifact` and download it in that job.
{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: echo "##vso[task.setvariable variable=SL_BSID;isOutput=true]$(cat buildSessionId)"
  name: sealights
  displayName: Keep the build session ID
```

In a later job, map `$[ dependencies.<job>.outputs['sealights.SL_BSID'] ]` to a variable and pass it with `--buildSessionId`.
{% endtab %}

{% tab title="PowerShell" %}

```powershell
$env:SL_buildSessionId = (Get-Content buildSessionId -Raw).Trim()
```

{% endtab %}
{% endtabs %}

## Pull request builds <a href="#pull-request-builds" id="pull-request-builds"></a>

In a pipeline that runs for a pull request, use `prConfig` instead of `config`. SeaLights then compares the pull request with its target branch. It writes the build session ID to the same file, so the rest of the pipeline does not change.

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npx slnodejs prConfig --tokenFile sltoken.txt --appName "my-app" \
  --targetBranch main \
  --latestCommit "$PR_HEAD_SHA" \
  --pullRequestNumber "$PR_NUMBER" \
  --repositoryUrl "https://github.com/my-org/my-app"
```

All four PR flags are required. See [`prConfig` in the Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md#prconfig).

## Next step <a href="#next-step" id="next-step"></a>

[Scan your application](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/scanning-your-application.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
