Skip to content

Code Insights & Coverage

TL;DR — Coverage reporting uses the native Bitbucket Code Insights API to show coverage directly in PRs with line-level annotations. Two components: an npm package that runs in Pipelines, and a Forge app that gates merges.

Overview

Coverage reporting and merge blocking are handled by two components working together:

Pipeline (runs on push)              Forge App (runs on merge click)
┌─────────────────────┐              ┌──────────────────────┐
│ npm run test:cov    │              │ Read report from     │
│ npx @securitize/    │──> Report ──>│ Bitbucket API        │
│ coverage-insights   │   (PASSED/   │                      │
│                     │    FAILED)   │ PASSED → allow merge │
└─────────────────────┘              │ FAILED → block merge │
                                     └──────────────────────┘

Components

1. @securitize/coverage-insights (npm package)

  • Repo: https://bitbucket.org/securitize_dev/commons-shared/src/master/packages/coverage-insights/
  • Monorepo: lives inside commons-shared — see shared-libraries.md.
  • What it does: runs in Bitbucket Pipelines, parses LCOV coverage reports, calculates total + patch coverage, posts Code Insights reports and annotations to PRs.
  • Published to: private npm (@securitize scope).

Usage in pipelines: 

- step: &coverage_report
    name: Coverage Report
    script:
      # Docs & env vars: https://bitbucket.org/securitize_dev/commons-shared/src/master/packages/coverage-insights/README.md
      - npx @securitize/coverage-insights

2. coverage-merge-check (Forge app)

  • Repo: https://bitbucket.org/securitize_dev/coverage-merge-check
  • What it does: Atlassian Forge serverless app that acts as a Bitbucket Custom Merge Check. Triggers when someone clicks Merge, reads the coverage report, and blocks merge if FAILED.
  • Runtime: Atlassian Forge (serverless, hosted by Atlassian, zero infra).
  • Trigger: on-merge only — not on push (the report doesn't exist yet at push time).
  • Deploy: forge deploy from the repo.
  • Install: forge install --product bitbucket (once per workspace).

Environment variables

Coverage package (COV_IN_ prefix)

Variable Default Description
COV_IN_ENABLED true Kill switch
COV_IN_FILE coverage/lcov.info Path to LCOV report
COV_IN_TOTAL_THRESHOLD 60 Min total coverage %
COV_IN_PATCH_THRESHOLD 80 Min patch coverage %
COV_IN_TARGET_BRANCHES dev Comma-separated destination branches to analyze
COV_IN_IGNORE_MISSING true Skip if no coverage file (for frontends without tests)
COV_IN_ANNOTATIONS true Annotate uncovered lines in PR diff
COV_IN_FAIL_PIPELINE false Exit 1 if thresholds not met (blocks merge via pipeline)

Authentication (shared across Code Insights tools)

Variable Scope Description
BB_CODE_INSIGHTS_USER Workspace variable Bitbucket username (email)
BB_CODE_INSIGHTS_TOKEN Workspace variable (secured) Bitbucket API token

These are used by @securitize/coverage-insights to post reports to the Bitbucket API. Set once at workspace level — applies to all repos.

Enabling the merge check

Per repository

Repository settings → Custom merge checks → Coverage Merge Check → Add check → Select branch → Set as Required or Recommended.

Per workspace (applies to all repos)

Workspace settings → Custom merge checks → Coverage Merge Check → Add check → All branches.

Required = blocks merge if FAILED. Recommended = shows status but allows merge.

Safe when no report exists

The merge check allows merge when no report is posted (safe for repos without coverage-insights).

How reports appear in PRs

  1. Reports tab: shows Total Coverage %, Patch Coverage %, thresholds, PASSED/FAILED.
  2. Annotations: uncovered lines marked inline in the PR diff with "Line not covered by tests".
  3. Merge check: "Coverage Merge Check" in the merge checks sidebar (PASSED / DID NOT PASS).

Overriding per repository

Set Bitbucket repository variables to override workspace defaults:

Common overrides

  • Mature repo: COV_IN_TOTAL_THRESHOLD=90
  • Legacy repo: COV_IN_TOTAL_THRESHOLD=40
  • Team PRing to rc: COV_IN_TARGET_BRANCHES=dev,rc
  • Disable for a repo: COV_IN_ENABLED=false

Bitbucket Test Reporting (complementary)

Not part of Code Insights but configured alongside it. Bitbucket natively detects JUnit XML test reports and shows a "Tests" tab in the pipeline UI. See bitbucket-ci.md for setup.

See also

Tags

coverage #code-insights #bitbucket #forge #merge-check