Getting started with Code Coverage in CodeScene

This guide helps you set up code coverage in CodeScene as quickly as possible. By the end of this guide, you will have:

  1. Generated code coverage data in your CI pipeline.

  2. Uploaded the results to CodeScene with the Coverage CLI.

  3. Run or wait for a new CodeScene analysis.

  4. Verified the results in the Code Coverage dashboard and Explore view.

What CodeScene does

CodeScene does not generate code coverage data itself. Your test tools generate the coverage report, and CodeScene ingests that data so you can visualize and explore it. The basic workflow is: Generate coverage in CI -> Upload it to CodeScene -> Run a new analysis -> Verify the results in CodeScene If you want to check or block pull requests based on coverage, use the separate guide for Code Coverage gates. This guide focuses on uploading coverage data so it can be visualized in CodeScene.

Before you start

Make sure you have the following in place:

  • A CodeScene project that already analyzes your repository.

  • A CI/CD pipeline that runs your tests.

  • A coverage tool that outputs a format supported by CodeScene.

  • A Personal Access Token for the Coverage CLI.

  • Git available in the environment where cs-coverage upload runs.

Supported formats and metrics

CodeScene supports multiple coverage formats and metrics. Common examples include:

  • lcov: line-coverage, branch-coverage, function-coverage

  • cobertura: line-coverage

  • jacoco: line-coverage, branch-coverage

  • open-cover: line-coverage, sequence-point-coverage, method-coverage, branch-coverage

  • open-clover: line-coverage, method-coverage, condition-coverage, statement-coverage

  • dotcover: line-coverage, statement-coverage

  • ncover: line-coverage, sequence-point-coverage

  • bullseye: line-coverage, method-coverage, condition-decision-coverage, decision-coverage

You can upload multiple metrics for the same repository. Each metric appears as a separate coverage type in CodeScene.

Step 1: Create your access token

The Coverage CLI uses a Personal Access Token (PAT). To create one, in your CodeScene instance go to Configuration → Authentication → Internal User Management → Personal Access Tokens. For full details, see How to create and use Personal Access Tokens in CodeScene. Then configure the required environment variables:

  • CS_ONPREM_URL — the base URL of your CodeScene instance (for example https://your.codescene.com).

    • Alternatively, use CS_ONPREM_API_URL, which must include /api/v2 at the end.

  • CS_ACCESS_TOKEN — your Personal Access Token.

Linux/macOS:

export CS_ONPREM_URL=https://your.codescene.com 
export CS_ACCESS_TOKEN=<your-pat-token>

PowerShell:

$env:CS_ONPREM_URL = 'https://your.codescene.com' 
$env:CS_ACCESS_TOKEN = '<your-pat-token>'

Command Prompt:

set "CS_ONPREM_URL=https://your.codescene.com" 
set "CS_ACCESS_TOKEN=<your-pat-token>"

Note: In Command Prompt, make sure not to put spaces around the =. Writing set "CS_ONPREM_URL = https://..." creates a variable name with a trailing space and a value with a leading space, which causes the CLI to fail. Note: Some PAT characters may need escaping depending on your shell. If authentication fails unexpectedly, check for special characters in the token.

Step 2: Install the Coverage CLI

Install the CodeScene Coverage CLI in the environment where your CI pipeline runs the coverage upload. The easiest option is to use the install script. If your environment does not allow install scripts, you can also download and install the binary manually.

Option A: Install with the script Linux, macOS, and Windows with WSL:

curl https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | sh

PowerShell:

Invoke-WebRequest -Uri 'https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.ps1' -OutFile install-cs-coverage-tool.ps1 .\install-cs-coverage-tool.ps1

To verify the installation:

cs-coverage version

Option B: Manual installation

Use manual installation if you cannot run the install script, for example in restricted on-prem environments or locked-down CI runners.

  1. Download the correct cs-coverage binary for your operating system and architecture.

  2. Extract the archive if needed.

  3. Move the binary to a directory on your PATH.

  4. Verify that the command works.

Linux/macOS example:

chmod +x cs-coverage 
sudo mv cs-coverage /usr/local/bin/ 

cs-coverage version

Windows PowerShell example:

# Place cs-coverage.exe in a folder such as C:\tools\cs-coverage
# Then add that folder to PATH for the current user.
[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";C:\tools\cs-coverage",
  "User"
)

cs-coverage version

If cs-coverage version is not found, check that the binary location is included in PATH and restart the terminal or CI shell session.

CI-friendly installation without sudo

Some CI environments do not allow sudo or global installation. In that case, install the binary into a local tools directory and add it to PATH for the current job. Example:

mkdir -p .codescene/bin 

# Download or copy the cs-coverage binary into .codescene/bin 

chmod +x .codescene/bin/cs-coverage 
export PATH="$PWD/.codescene/bin:$PATH" 

cs-coverage version

Use this approach when the CI runner is ephemeral or when you want the installation to be fully contained inside the workspace.

Version stability and the full command reference The install script and the manual download links always resolve to the latest release — there is currently no supported way to pin the Coverage CLI to a specific version. If pipeline reproducibility matters to your team, download the binary once and cache it in your CI system (see the GitLab CI example below) so the same binary is reused across runs until you deliberately update it. To see every available flag for cs-coverage upload, cs-coverage check, and other subcommands, run cs-coverage --help or cs-coverage <command> --help (for example cs-coverage upload --help).

Step 3: Generate coverage in your CI pipeline

CodeScene does not create the coverage report. Your build or test step must generate it first. Examples:

  • JavaScript/TypeScript projects often produce LCOV.

  • Java projects often produce JaCoCo XML.

  • .NET projects may produce OpenCover or dotCover output.

If your repository contains multiple languages or multiple independently generated reports, you may need multiple uploads.

Step 4: Upload coverage to CodeScene

Upload coverage from the repository root after the coverage report has been generated. Examples:

# LCOV line coverage 
cd /path/to/your/repository 
cs-coverage upload --format lcov --metric line-coverage coverage/code-coverage.lcov 
# LCOV branch coverage from the same report 
cd /path/to/your/repository 
cs-coverage upload --format lcov --metric branch-coverage coverage/code-coverage.lcov 
# JaCoCo line coverage 
cd /path/to/your/repository 
cs-coverage upload --format jacoco --metric line-coverage target/site/jacoco/jacoco.xml 
# JaCoCo branch coverage 
cd /path/to/your/repository 
cs-coverage upload --format jacoco --metric branch-coverage target/site/jacoco/jacoco.xml 
# Cobertura line coverage 
cd /path/to/your/repository 
cs-coverage upload --format cobertura --metric line-coverage coverage/cobertura-coverage.xml 
# OpenCover branch coverage 
cd /path/to/your/repository 
cs-coverage upload --format open-cover --metric branch-coverage TestResults/coverage.opencover.xml

Important rules for uploads

  • Run the uploader from the repository root.

  • Make sure the local checkout matches the same commit or branch that CodeScene analyzes.

  • Run the upload immediately after the coverage report is generated whenever possible.

  • If multiple uploads contain data for the same file, CodeScene uses the most recent applicable upload for that file.

  • Coverage data is uploaded per Git repository.

Upload command examples by format

Use the format, metric, and file path that match the report your test tooling actually generates. CodeScene supports multiple formats and metrics, and you can upload multiple metrics for the same repository.

Golden path: GitHub Actions

This example shows a complete GitHub Actions workflow for uploading coverage data to CodeScene. Replace the test command and coverage file path with the values used by your project.

name: Upload Code Coverage to CodeScene

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  coverage:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run tests and generate coverage
        run: |
          # Replace this with your project's actual test command
          # and make sure it generates a supported coverage report.
          echo "Run tests here and generate coverage"

      - name: Install CodeScene Coverage CLI
        run: curl https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | bash -s -- -y

      - name: Upload coverage data to CodeScene
        run: cs-coverage upload --format "lcov" --metric "line-coverage" "coverage/code-coverage.lcov"
        env:
          CS_ONPREM_URL: ${{ secrets.CS_ONPREM_URL }}
          CS_ACCESS_TOKEN: ${{ secrets.CS_ACCESS_TOKEN }}

What to update in this workflow:

  • Replace the test command with the one your project actually uses.

  • Make sure the test step produces a supported coverage report.

  • Change --format, --metric, and the file path to match your report.

  • Store CS_ONPREM_URL and CS_ACCESS_TOKEN as repository or organization secrets.

GitLab CI, Azure DevOps, Jenkins, and other providers

The provider does not matter as long as the pipeline does the same four things:

  1. Check out the repository.

  2. Run tests and generate a supported coverage report.

  3. Install cs-coverage.

  4. Run cs-coverage upload from the repository root.

For non-GitHub providers, the most important thing is that the upload runs in the same checked-out repository and on the same commit or branch that CodeScene will analyze.

GitLab CI example (.gitlab-ci.yml):

stages:
  - test

upload_coverage:
  stage: test
  image: ubuntu:22.04
  variables:
    CS_ONPREM_URL: $CS_ONPREM_URL
    CS_ACCESS_TOKEN: $CS_ACCESS_TOKEN
  cache:
    key: cs-coverage-cli-v1
    paths:
      - .codescene/bin/
  before_script:
    - mkdir -p .codescene/bin
    - |
      if [ ! -x .codescene/bin/cs-coverage ]; then
        curl -sSL https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | sh
        mv cs-coverage .codescene/bin/ 2>/dev/null || true
      fi
    - export PATH="$PWD/.codescene/bin:$PATH"
  script:
    # Replace with your project's actual test command and coverage output path
    - echo "Run tests here and generate coverage"
    - cs-coverage upload --format lcov --metric line-coverage coverage/code-coverage.lcov

Store CS_ONPREM_URL and CS_ACCESS_TOKEN as masked CI/CD variables under Settings → CI/CD → Variables. Caching .codescene/bin/ between jobs also avoids re-downloading the CLI on every run, which helps with the version-stability point above.

Azure DevOps example (azure-pipelines.yml):

trigger:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - checkout: self

  - script: |
      echo "Run tests here and generate coverage"
    displayName: 'Run tests and generate coverage'

  - script: |
      curl https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | bash -s -- -y
    displayName: 'Install CodeScene Coverage CLI'

  - script: |
      cs-coverage upload --format lcov --metric line-coverage coverage/code-coverage.lcov
    displayName: 'Upload coverage to CodeScene'
    env:
      CS_ONPREM_URL: $(CS_ONPREM_URL)
      CS_ACCESS_TOKEN: $(CS_ACCESS_TOKEN)

Define CS_ONPREM_URL and CS_ACCESS_TOKEN as pipeline variables (mark the token "keep this value secret") under the pipeline's Variables settings.

Jenkins example (declarative Jenkinsfile):

pipeline {
    agent any

    environment {
        CS_ONPREM_URL = credentials('cs-onprem-url')
        CS_ACCESS_TOKEN = credentials('cs-access-token')
    }

    stages {
        stage('Test') {
            steps {
                sh 'echo "Run tests here and generate coverage"'
            }
        }

        stage('Install Coverage CLI') {
            steps {
                sh 'curl https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | bash -s -- -y'
            }
        }

        stage('Upload Coverage') {
            steps {
                sh 'cs-coverage upload --format lcov --metric line-coverage coverage/code-coverage.lcov'
            }
        }
    }
}

Store the URL and token as Jenkins credentials (Manage Jenkins → Credentials) rather than plain environment variables.

Step 5: Run or wait for a new analysis

Uploaded coverage data only becomes visible in the Project Dashboard after a new CodeScene analysis runs. If your project is already analyzed automatically, wait for the next analysis. To trigger an analysis manually:

curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \ 'https://your.codescene.com/api/v2/projects/{project-id}/run-analysis'

Replace <token> with the same Personal Access Token you created in Step 1, and {project-id} with your project's ID. If you don't already know the ID, list your projects with the same token to find it:

curl -X GET --header "Accept: application/json" --header "Authorization: Bearer <token>" "https://your.codescene.com/api/v2/projects"

See How Do I Use CodeScene's REST API On-Prem? for more on authenticating against the REST API. Availability of this endpoint may depend on your CodeScene plan — check with your CodeScene contact if you're unsure.

Step 6: Verify the results in CodeScene

After the next analysis completes, verify the result in these places:

  • Code Coverage dashboard: review overall coverage, hotspot coverage, uncovered files, and trends over time.

  • Explore view: inspect code coverage on the system map and drill down to folders and files.

  • Analysis warnings: if coverage does not line up with the analyzed commit, check warnings in Project Dashboard -> Scope -> Analysis Data -> Analysis Warnings.

Common mistakes and what to check Coverage is not visible in CodeScene Check the following:

  • A new analysis has run after the upload.

  • The upload used the correct repository checkout.

  • The upload was performed from the repository root.

  • The format, metric, and file path match the generated report.

Some files show no coverage This can happen when:

  • Coverage was uploaded for an ancestor commit and those files changed afterwards.

  • Coverage is only generated for part of the codebase.

  • A language or repository in a larger setup is not covered yet.

The results look incomplete or misleading Remember:

  • CodeScene only uses coverage data that matches the same commit or an ancestor commit.

  • If coverage is from an ancestor commit, files changed since then will not show coverage data.

  • CodeScene does not merge coverage data for the same file across uploads.

Authentication errors (401/403) Check the following:

  • CS_ACCESS_TOKEN is set, and has not expired or been revoked.

  • The token has the permissions required for the Coverage CLI.

  • CS_ONPREM_URL (or CS_ONPREM_API_URL) points to the correct CodeScene instance, with no typos and the correct protocol.

Network or connection errors Check the following:

  • The environment running cs-coverage upload can reach your CodeScene instance over HTTPS.

  • If you're behind a corporate proxy or firewall, see your organization's CodeScene proxy configuration documentation.

  • Persistent SSL/TLS certificate errors on-prem may require installing your organization's CA certificate.

Excluding false positives

If some files or folders do not have coverage data yet, CodeScene may treat them as 0% coverage by default. To avoid misleading results, define code coverage exclusions in the project configuration using glob patterns relative to the repository root, for example:

"**/vendor/**" "**/node_modules/**" "test/**" "**/*.generated.cs"

Excluded files appear as grey circles in the system map and do not affect the code coverage KPIs and averages.

Coverage data retention If you need to know how long uploaded coverage data is retained, or whether old uploads are pruned, check with your CodeScene contact — this is not yet documented here.

Next step: Code Coverage gates for pull requests

If you want to enforce coverage in pull requests or merge requests, continue with the separate guide for Code Coverage gates. That setup is different from the upload flow in this guide:

  • coverage uploads are for visualization and analytics in CodeScene

  • coverage gates run in CI and evaluate pull requests or build results