GitHub Actions

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

For a complete working example, see 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 format
  4. Upload – Send results to Codecov or similar services

Setup Action

Install covdbg on your runner using the official action:

- name: Setup covdbg
  uses: covdbg/setup-covdbg@v0
  with:
    version: '1.0.0'  # Specify version or use 'latest'Code language: YAML (yaml)

Running Coverage

Open Source Projects

For open source projects, covdbg automatically fetches a free license:

- name: Run Coverage
  shell: pwsh
  env:
    COVDBG_APPDATA: .covdbg
    # Automatically queries for a license as the repository is public
    COVDBG_FETCH_LICENSE: true
  run: |
    covdbg --config .covdbg.yaml --output tests.covdb tests.exeCode language: YAML (yaml)

Commercial Projects

For commercial projects, store your license token as a GitHub Secret named COVDBG_LICENSE:

- name: Run Coverage
  shell: pwsh
  env:
    COVDBG_APPDATA: .covdbg
    # Use license token from secrets
    COVDBG_LICENSE: ${{ secrets.COVDBG_LICENSE }}
  run: |
    covdbg --config .covdbg.yaml --output tests.covdb tests.exeCode language: YAML (yaml)

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.lcovCode language: YAML (yaml)

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 }}Code language: YAML (yaml)

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.lcovCode language: YAML (yaml)

Advanced Configuration

Caching AppData

The COVDBG_APPDATA directory contains logs and cached license information. Caching it provides:

  • License failover: Grace periods during network outages
  • Debugging: Upload as artifact to inspect detailed logs
- name: Cache covdbg appdata
  uses: actions/cache@v4
  with:
    path: .covdbg
    key: covdbg-appdata-${{ runner.os }}

- name: Run Coverage
  shell: pwsh
  env:
    COVDBG_LICENSE: ${{ secrets.COVDBG_LICENSE }}
    COVDBG_APPDATA: .covdbg
  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/Code language: YAML (yaml)

Silent Mode

Use COVDBG_LOG_LEVEL to suppress output:

env:
  COVDBG_LOG_LEVEL: NONECode language: YAML (yaml)

Troubleshooting

License Issues

If coverage fails with license errors:

  1. Verify COVDBG_LICENSE secret is set correctly (commercial) or COVDBG_FETCH_LICENSE: true (open source)
  2. Check the license hasn’t expired
  3. Ensure no typos or extra whitespace in the token
  4. Upload the .covdbg/ appdata 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/ appdata directory as an artifact to inspect logs

Debugging CI Failures

Set COVDBG_APPDATA: .covdbg and upload the directory as an artifact:

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

See Also