How do you use the Bitbucket Code Insights API to integrate external code analysis tools and surface findings directly in pull requests?

Think of Code Insights like post-it notes from a team of specialist reviewers who examined your code before the human reviewers even look at it. One specialist (SonarQube) notes code smells, another (Checkmarx) flags security vulnerabilities, and a third (your custom linter) highlights style violations. All their notes appear directly on the pull request, right next to the code lines they concern, so human reviewers can focus on logic and architecture rather than catching mechanical issues.

The Code Insights API is a Bitbucket feature that allows external tools to publish structured analysis results into pull requests. It has two components: Reports and Annotations. A Report is a top-level summary (like 'SonarQube Analysis') with a status (PASSED or FAILED), a link to the full external report, and metadata like the number of issues found. Annotations are line-level findings attached to the report, each with a file path, line number, severity (HIGH, MEDIUM, LOW), and a description. In Bitbucket Cloud, reports are submitted via the /2.0/repositories/{workspace}/{repo}/commit/{commit}/reports/{reportId} endpoint, and annotations via the /annotations sub-endpoint.

The implementation pattern follows a standard flow. A pipeline step runs the analysis tool (SonarQube scanner, ESLint, custom static analysis). The tool produces a results file (JSON, XML, or proprietary format). A post-processing script parses the results and transforms them into the Code Insights API format. The script submits the report and annotations via REST API calls. Bitbucket displays the report in the PR's 'Code Insights' tab and renders annotations as inline markers in the diff view. If a report's status is FAILED and a merge check is configured to require passing Code Insights reports, the PR cannot be merged until the issues are fixed.

In production, teams use Code Insights to build a comprehensive quality gate that goes beyond just 'tests pass.' A mature setup includes a SonarQube report for code quality (duplication, complexity, code smells), a security scanner report (Checkmarx, Snyk, or Trivy for container scanning), a code coverage report (showing which lines the tests exercise), and optionally a performance analysis report (lighthouse scores for frontend, benchmark results for backend). Each report can independently block the merge if it fails its threshold. This creates a multi-dimensional quality gate where a PR must satisfy code quality, security, coverage, and performance criteria simultaneously.

A gotcha that limits Code Insights effectiveness: annotations are attached to specific commit SHAs, not to the PR itself. If a developer pushes a new commit, the annotations from the previous commit are no longer displayed. The analysis tool must re-run on every new commit and re-submit annotations. This means the pipeline step running the analysis must be configured on the pull-requests trigger, not just the branch trigger. Another limitation in Bitbucket Cloud: there is a maximum of 1,000 annotations per report and 100 reports per commit. If your analysis tool produces more than 1,000 findings, you must aggregate or prioritize them before submission.