Code Insights

Code insights provides reports, annotations, and metrics to help you and your team improve code quality in pull requests throughout the code review process. Some of the available code insights are static analysis reports, security scan results, artifact links, unit tests, and build status.

Prerequisites

You must have a Bitbucket Cloud account.
You must have at least one pull request or pipeline.
If you are using pipelines, you have to use an integration. Learn more

If you are a third-party provider, adding reports to Bitbucket Cloud is a way to get information, such as code coverage, code quality and deployment information, into a pull request. If you are looking for existing integrations, there are a number of existing tools that post reports to Bitbucket Cloud in our Marketplace.

Reports

View reports in pull requests

Go to the pull request.
Click Reports on the left navigation sidebar. You can also view your reports via the right sidebar.

If you haven’t set up a pipe or an integration, you won’t be able to view any reports. Check the list of available pipes, or learn how to write a pipe.

View annotated reports in diff view

If you have reports, annotations are enabled by default, so you will be able to see annotated reports displayed within a line or per file. To see an aggregated view of the available annotations, click the Report section (card) on the right sidebar.

Disable or hide report annotations

To disable annotations from your diff view, select the Settings button in the upper-right corner of the pull request and select the Annotations checkbox listed under Show.

To hide annotations on a specific pull request, select the ‘More options’ button ( … ) > click Hide annotations.

View reports in a pipeline

Select Pipelines on the left navigation sidebar.
Select the pipeline you want to see the reports for.
Click the # reports link at the bottom of the pipeline modal to see the detailed reports.

Use the Reports-API to upload reports

Third-party providers also have the option to upload reports directly through the REST-API. Reports are based against a commit.

The full Open API documentation of the REST API for code reports can be found at the following link: https://developer.atlassian.com/bitbucket/api/2/reference/search?q=tag:reports

Creating reports

To create a report, make sure to generate an ID that is unique across all reports for that commit. If you want to use an existing ID from your own system, we recommend prefixing it with your system’s name to avoid collisions, for example, mySystem-001.

Example cURL request

curl --request PUT 'https://api.bitbucket.org/2.0/repositories/<username>/<repository-name>/commit/<commit-hash>/reports/mySystem-001' \
--header 'Content-Type: application/json' \
--data-raw '{
	"title": "Security scan report",
	"details": "This pull request introduces 10 new dependency vulnerabilities.",
	"report_type": "SECURITY",
	"reporter": "mySystem",
	"link": "http://www.mySystem.com/reports/001",
	"result": "FAILED",
	"data": [
		{
			"title": "Duration (seconds)",
			"type": "DURATION",
			"value": 14
		},
		{
			"title": "Safe to merge?",
			"type": "BOOLEAN",
			"value": false
		}
	]
}'

title, details and report_type are the only mandatory fields in the payload. The elements under the data array can be freely defined. They can represent any information you want to communicate to the user. Report data is mandatory and can contain up to 10 elements. The information contained in that array will be displayed at the top of a report along with the other fields in the payload.

The same endpoint can also be used to update existing reports. The URL is also available as a GET and a DELETE endpoint. Once created, a report can be addressed with the generated UUID instead of the external id. Additionally, a GET for …/<commit-hash>/reports without an ID returns all reports belonging to this commit.

Jira users only: Remote links are now available in Jira. To add remote links to your reports, set the remote-link-enabled field to ‘true’ in the create payload. These reports will be displayed on the Other links tab in Jira and in the your Reports in Bitbucket.

Annotations

Annotations are individual findings that have been identified as part of a report, for example, a line of code that represents a vulnerability. These annotations can be attached to a specific file and even a specific line in that file; however, that is optional. Annotations are not mandatory and a report can contain up to 1000 annotations.

Just as reports, annotation needs to be uploaded with a unique ID that can later be used to identify the report as an alternative to the generated UUID.

Example: cURL request:

curl --request PUT 'https://api.bitbucket.org/2.0/repositories/<username>/<reposity-name>/commit/<commit-hash>/reports/mySystem-001/annotations/mySystem-annotation001' \
--header 'Content-Type: application/json' \
--data-raw '{
	"title": "Security scan report",
	"annotation_type": "VULNERABILITY",
	"summary": "This line represents a security thread.",
	"severity": "HIGH",
	"path": "my-service/src/main/java/com/myCompany/mySystem/logic/Main.java",
	"line": 42
}'

annotation_type and summary are the only mandatory fields in the payload.

The same endpoint can also be used to update existing reports. The URL is available as a GET and as a DELETE endpoint. Additionally, POST …/annotations offers bulk options. With this endpoint up to 100 annotations can be created or updated at once. The payload needs to contain a JSON-array of annotation objects.

Authentication

Using Bitbucket Pipelines allows you to use the Reports-API without extra authentication. For that you need to send your request through a proxy server that runs alongside with every pipeline on ‘localhost:29418’, and a valid Auth-Header will automatically be added to your request.

Example cURL request

curl --proxy 'http://localhost:29418' --request PUT "http://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG/commit/$BITBUCKET_COMMIT/reports/mySystem-001/annotations/mySystem-annotation001"

If you develop a custom pipe you can also use the same proxy server; however, because pipes are running inside a docker container, the URL is slightly different.

Example cURL request

curl --proxy 'http://host.docker.internal:29418' --request PUT "http://api.bitbucket.org/2.0/repositories/$BITBUCKET_REPO_OWNER/$BITBUCKET_REPO_SLUG/commit/$BITBUCKET_COMMIT/reports/mySystem-001/annotations/mySystem-annotation001"

For calls from outside of Bitbucket, see Bitbucket API developer doc for Authentication methods. For the Reports-API, you will need to have access to the repository and use the repository scopes. See the Scopes for the Bitbucket Cloud REST API section in the Bitbucket API developer doc for Authentication methods.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community