> 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/integrations/pull-request-integration/legacy-integration/bitbucket-pull-request.md).

# BitBucket Pull Request

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 <a href="#analyzingabitbucketpullrequest-creatingapersonalaccesstokenonbitbucket" id="analyzingabitbucketpullrequest-creatingapersonalaccesstokenonbitbucket"></a>

* 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:

| ![](https://sealights.atlassian.net/wiki/download/thumbnails/604209153/image2019-4-3_21-23-56.png?version=1\&modificationDate=1554315841004\&cacheVersion=1\&api=v2\&width=185\&height=250) | ![](https://sealights.atlassian.net/wiki/download/thumbnails/604209153/image2019-4-3_21-30-20.png?version=1\&modificationDate=1554316223851\&cacheVersion=1\&api=v2\&width=511\&height=400) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
The application will **not modify** anything in your repositories and projects as it only requires **Read** access.
{% endhint %}

## SeaLights Task Runner App Configuration <a href="#analyzingabitbucketpullrequest-sealightstaskrunnerappconfiguration" id="analyzingabitbucketpullrequest-sealightstaskrunnerappconfiguration"></a>

* To report the Pull Request data to SeaLights, the Task Runner must be installed on a machine with network access to the BitBucket server:
  1. Download the Task Runner from the following link: <https://agents.sealights.co/sl_task_runner/sl_task_runner-4.0.2397.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:
     * The token to be used should be an [Agent token](https://docs.sealights.io/knowledgebase/setup-and-configuration/getting-started/steps-for-successful-onboarding/generating-a-token#agent-tokens)

**sl-taskrunner-cfg.json example**

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

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

{% endcode %}

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

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

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

{% endcode %}

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

Running the SeaLights Task Runner using Java parameters

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

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

{% endcode %}

{% hint style="info" %}
See [Task Runner Agent - Command Reference](/knowledgebase/setup-and-configuration/integrations/pull-request-integration/legacy-integration/task-runner-agent-command-reference.md) for full list of parameters.
{% endhint %}

## Configuring the BitBucket Pull Request to compare data to SeaLights <a href="#analyzingabitbucketpullrequest-configuringthebitbucketpullrequesttocomparedatatosealights" id="analyzingabitbucketpullrequest-configuringthebitbucketpullrequesttocomparedatatosealights"></a>

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.\
The difference between the pull request job and standard jobs is in how the **session ID is created** using Pull Request **specific parameters**.

### Generating a session ID <a href="#analyzingabitbucketpullrequest-generatingasessionid" id="analyzingabitbucketpullrequest-generatingasessionid"></a>

You create the Pull Request build session ID by using the SeaLights Java Build Scanner (See: [Downloading The Java Agent](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/java-agent/default-usage-cli/downloading-the-java-agent.md) with the **prConfig** option:

Sample prConfig command

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

```
java -jar sl-build-scanner.jar -prConfig -appname "MyApp" -latestCommit $BITBUCKET_COMMIT -pullRequestNumber $BITBUCKET_PR_ID -repoUrl $BITBUCKET_REPO_SLUG -targetBranch origin/$BITBUCKET_PR_DESTINATION_BRANCH -tokenfile sl_acc_token.txt -pi "*co.sealights.sample.*"
```

{% endcode %}

{% hint style="warning" %}
For Java applications, 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
{% endhint %}

{% hint style="info" %}
See [prConfig - Command Reference](/knowledgebase/setup-and-configuration/integrations/pull-request-integration/prconfig-command-reference.md) for full parameter details in **Java agent, node agent** or via the Sealights **Jenkins plugin.**
{% endhint %}

### Pull Request parameters as seen on a Bitbucket page <a href="#analyzingabitbucketpullrequest-pullrequestparametersasseenonabitbucketpage" id="analyzingabitbucketpullrequest-pullrequestparametersasseenonabitbucketpage"></a>

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

<figure><img src="https://sealights.atlassian.net/wiki/download/thumbnails/604209153/image2019-6-6_11-53-22.png?version=1&#x26;modificationDate=1559811206813&#x26;cacheVersion=1&#x26;api=v2&#x26;width=807&#x26;height=400" alt=""><figcaption></figcaption></figure>

### Pull Request parameters mapping with Bitbucket Environment variables <a href="#analyzingabitbucketpullrequest-pullrequestparametersmappingwithbitbucketenvironmentvariables" id="analyzingabitbucketpullrequest-pullrequestparametersmappingwithbitbucketenvironmentvariables"></a>

Bitbucket provides a set of default variables that are available for builds, and can be used in scripts. These variables are detailed in the official [Bitbucket documentation](https://confluence.atlassian.com/bitbucket/environment-variables-794502608.html) and can be used like below

<table><thead><tr><th width="186.45703125">Sealights PR Parameter</th><th width="217.2265625">BitBucket Env. Variable</th><th>Comment</th></tr></thead><tbody><tr><td>pullRequestNumber</td><td>BITBUCKET_PR_ID</td><td><br></td></tr><tr><td>latestCommit</td><td>BITBUCKET_COMMIT</td><td><br></td></tr><tr><td>repoUrl</td><td>BITBUCKET_REPO_SLUG</td><td>In some configurations, you may need to prepend the base URL of your repository, like "<a href="https://bitbucket.mycompany.int/">https://bitbucket.mycompany.int/</a>$BITBUCKET_REPO_SLUG"</td></tr><tr><td>targetBranch</td><td>BITBUCKET_PR_DESTINATION_BRANCH</td><td>This is the branch name itself and might need to have a prefix added (Like: "origin/") to match the branch that was provided to SeaLights when scanning the merged branch</td></tr></tbody></table>

## Sample of Results on the BitBucket Pull Request page <a href="#analyzingabitbucketpullrequest-sampleofresultsonthebitbucketpullrequestpage" id="analyzingabitbucketpullrequest-sampleofresultsonthebitbucketpullrequestpage"></a>

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:

<figure><img src="https://sealights.atlassian.net/wiki/download/thumbnails/604209153/image2019-4-4_11-45-35.png?version=2&#x26;modificationDate=1560169702365&#x26;cacheVersion=1&#x26;api=v2&#x26;width=933&#x26;height=400" alt=""><figcaption></figcaption></figure>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/pull-request-integration/legacy-integration/bitbucket-pull-request.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.