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.

Reports

Add reports and view them in Bitbucket

Prerequisites

  • You must have a Bitbucket Cloud account.

  • If you have been a Bitbucket Cloud user prior to September 2019 or opted out of the new code review experience, you must enable it by clicking your profile avatar on the left navigation sidebar > Bitbucket Labs > New pull request experience

  • 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.

View reports in pull requests

  1. Go to the pull request.

  2. 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, click on the Viewing preferences icon and select the Enable annotations toggle.

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

hide_annotations

View reports in a pipeline

  1. Click Pipelines on the left navigation sidebar.

  2. Select the pipeline you want to see the reports for.

  3. 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 OpenAPI 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


Reports and Report data

To upload 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 curl --request PUT 'https://api.bitbucket.org/2.0/repositories/<username>/<reposity-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.

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:

1 2 3 4 5 6 7 8 9 10 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

1 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

1 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 the Repository. See the Scopes for the Bitbucket Cloud REST API section in the Bitbucket API developer doc for Authentication methods.

Additional Help

Ask the Community