C++ Code Coverage in GitHub Actions

Set up code coverage with covdbg in your GitHub Actions CI/CD pipeline.

For a complete working example, see liasoft/covdbg-quick-start.

Quick Start

A typical workflow involves these steps:

  1. Setup: install covdbg on your runner
  2. Run: execute your tests with coverage collection
  3. Convert: export to LCOV or Cobertura format
  4. Upload: send results to Codecov or similar services

Complete Workflow

Save this as .github/workflows/coverage.yml in a public repository with a CMake build. It builds the tests, measures them, and uploads LCOV and Cobertura reports as an artifact, with no secret:

name: Coverage

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  coverage:
    runs-on: windows-latest

    # A pull request from a fork gets no workflow token: skip it, not fail it.
    if: >-
      github.event_name != 'pull_request' ||
      github.event.pull_request.head.repo.full_name == github.repository

    permissions:
      contents: read
      id-token: write      # the whole credential for a public repository

    steps:
      - uses: actions/checkout@v4

      - name: Setup covdbg
        uses: liasoft/setup-covdbg@v1
        with:
          version: '1.5.1'

      # Replace with your own build. covdbg reads the tests' PDB files.
      - name: Build
        run: |
          cmake -S . -B build
          cmake --build build --config Debug

      # Fails the step when the tests fail, once the database is written.
      - name: Run Coverage
        shell: pwsh
        run: |
          covdbg --propagate-exit-code --config .covdbg.yaml `
            --output build\coverage.covdb build\Debug\tests.exe

      - name: Convert Coverage
        if: always()
        shell: pwsh
        run: |
          covdbg convert -i build\coverage.covdb -f LCOV -o build\coverage.lcov
          covdbg convert -i build\coverage.covdb -f COBERTURA -o build\coverage.xml

      - name: Upload Coverage Reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-reports
          path: |
            build/coverage.lcov
            build/coverage.xml

Change build\Debug\tests.exe and the build step to your own. A private repository adds env: COVDBG_PROJECT_TOKEN: ${{ secrets.COVDBG_PROJECT_TOKEN }} to Run Coverage, see A private repository carries a project token. To measure on ARM64 as well, see Windows on ARM runners, and to send the report to Codecov, Upload to Codecov.

Setup Action

Install covdbg on your runner using the official action:

- name: Setup covdbg
  uses: liasoft/setup-covdbg@v1
  with:
    version: '1.5.1'  # Specify version or use 'latest'

Windows on ARM runners

The action installs the covdbg build for the runner's architecture: on an x64 runner the x64 build, which measures x64 and 32-bit x86 programs, and on an ARM64 runner, such as GitHub's windows-11-arm, the ARM64 build, which measures ARM64 programs. ARM64 builds are available from covdbg 1.5.0. To measure both, run the job on both runners:

jobs:
  coverage:
    strategy:
      fail-fast: false
      matrix:
        os: [windows-latest, windows-11-arm]
    runs-on: ${{ matrix.os }}
    permissions:
      contents: read
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup covdbg
        uses: liasoft/setup-covdbg@v1
        with:
          version: '1.5.1'

      # Build the tests for the runner's architecture here.

      - name: Run Coverage
        shell: pwsh
        run: covdbg --propagate-exit-code --config .covdbg.yaml --output tests-${{ matrix.os }}.covdb build/tests.exe

The architecture input (x64 or arm64) picks a build other than the runner's. Given an ARM64 program, the x64 build exits with code 1 before running it and names the build to use. To report an x64 job and an ARM64 job together, merge their databases: covdbg merge keeps the two builds of a program side by side and adds up the lines of the sources they share; see Merging Multiple Test Runs.

Running Coverage

Authenticating

A workflow has nobody to sign in, so it carries a credential of its own. Which one depends on whether the repository is public.

A public repository needs no secret

From covdbg 1.5.0, grant the job id-token: write and configure nothing else:

jobs:
  coverage:
    runs-on: windows-latest
    permissions:
      contents: read
      id-token: write      # lets covdbg prove which repository this run belongs to

    steps:
      - name: Run Coverage
        shell: pwsh
        run: covdbg --propagate-exit-code --config .covdbg.yaml --output tests.covdb tests.exe

covdbg asks GitHub for the OIDC token the job can mint for itself and presents that. GitHub signs which repository the job runs in, and a public repository is free, so there is nothing to create and nothing to paste into your repository settings.

It licenses the public case and nothing else: a workflow token says which repository a job runs in, never who may pay for it. On a private repository the run is refused and asks for a project token.

GitHub does not mint a token for a pull request from a fork, for the same reason it withholds secrets there, and no permissions: block changes that. So measure coverage on pushes to your default branch and on pull requests opened from your own repository, and skip fork pull requests rather than letting them fail:

    if: >-
      github.event_name != 'pull_request' ||
      github.event.pull_request.head.repo.full_name == github.repository

Do not reach for pull_request_target to work around this: it runs with your repository's own credentials and would execute code from the fork.

A private repository carries a project token

Store it as a GitHub Secret named COVDBG_PROJECT_TOKEN:

- name: Run Coverage
  shell: pwsh
  env:
    COVDBG_PROJECT_TOKEN: ${{ secrets.COVDBG_PROJECT_TOKEN }}
  run: |
    covdbg --propagate-exit-code --config .covdbg.yaml --output tests.covdb tests.exe

The token covers the commit authors who hold a seat in the team it belongs to; an author without one is granted for a grace period and listed on the team's members page, where an owner invites them. A project token also works on a public repository, and takes precedence when both are available, which is how a covdbg before 1.5.0 runs in CI at all.

Failing the step when tests fail

covdbg exits 0 once it has measured the run and written the database, also when the tests failed. From covdbg 1.5.1, --propagate-exit-code makes the step fail with the tests, which is why every example on this page passes it:

- name: Run Coverage
  shell: pwsh
  run: covdbg --propagate-exit-code --config .covdbg.yaml --output tests.covdb tests.exe

The database is written before covdbg exits, so the steps after it, which convert, merge and upload, run with if: always() on this page: they still report the coverage of a failing run, and the job still fails. See Exit Codes.

Converting to LCOV

Convert coverage results to LCOV format for use with reporting services:

- name: Convert to LCOV
  if: always()
  shell: pwsh
  run: |
    covdbg convert --input tests.covdb --format LCOV --output coverage.lcov

Upload to Codecov

Upload LCOV coverage to Codecov for reporting:

- name: Upload to Codecov
  if: always()
  uses: codecov/codecov-action@v5
  with:
    files: coverage.lcov
    fail_ci_if_error: true
    token: ${{ secrets.CODECOV_TOKEN }}

Merging Multiple Test Runs

If you have separate test suites, merge coverage databases before converting:

- name: Merge coverage
  if: always()
  shell: pwsh
  run: |
    covdbg merge --input tests.covdb --input tests2.covdb --output merged.covdb
    covdbg convert --input merged.covdb --format LCOV --output coverage.lcov

Advanced Configuration

Inspecting Logs

covdbg writes its log to .covdbg/Logs in the working directory. Upload that directory as an artifact to inspect a run:

- name: Run Coverage
  shell: pwsh
  env:
    COVDBG_PROJECT_TOKEN: ${{ secrets.COVDBG_PROJECT_TOKEN }}
  run: |
    covdbg --propagate-exit-code --config .covdbg.yaml --output build\Debug\tests.covdb build\Debug\tests.exe

- name: Upload covdbg logs (for debugging)
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: covdbg-logs
    path: .covdbg/

No Log File

covdbg never writes its log to the console, so your test output stays clean. To skip the log file as well:

env:
  COVDBG_LOG_LEVEL: NONE

Troubleshooting

License Issues

If coverage fails with license errors:

  1. Verify the COVDBG_PROJECT_TOKEN secret is set and reaches the step as an environment variable
  2. Ensure no typos or extra whitespace in the token
  3. Upload the .covdbg/ directory as an artifact to inspect logs

No Coverage Output

If .covdb file is empty or missing data:

  1. Ensure PDB files are present alongside your binaries
  2. Check that your include/exclude filters in .covdbg.yaml aren't too restrictive
  3. Set COVDBG_LOG_LEVEL: DEBUG to see detailed output
  4. Upload the .covdbg/ directory as an artifact to inspect logs

Debugging CI Failures

Upload the .covdbg/ directory as an artifact:

- name: Upload covdbg logs
  uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: covdbg-logs
    path: .covdbg/

See Also