GitHub Actions

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

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

Quick Start

A typical workflow involves these steps:

Setup - Install covdbg on your runner
Run - Execute your tests with coverage collection
Convert - Export to LCOV format
Upload - Send results to Codecov or similar services

Setup Action

Install covdbg on your runner using the official action:

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

Running Coverage

Authenticating

A workflow has nobody to sign in, so it 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 --config .covdbg.yaml --output tests.covdb tests.exe

Public repositories are free but a workflow still carries a token, since it has nobody to sign in; a token from your personal team will do, see Open Source. 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 pull request from a fork receives no secrets, so on a private repository the step has no credential there and is refused - skip it for fork pull requests, or accept that it fails.

Converting to LCOV

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

- name: Convert to LCOV
  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
  uses: codecov/codecov-action@v4
  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
  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 --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:

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

No Coverage Output

If .covdb file is empty or missing data:

Ensure PDB files are present alongside your binaries
Check that your include/exclude filters in .covdbg.yaml aren't too restrictive
Set COVDBG_LOG_LEVEL: DEBUG to see detailed output
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/