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:
- Setup: install covdbg on your runner
- Run: execute your tests with coverage collection
- Convert: export to LCOV or Cobertura format
- 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:
- Verify the
COVDBG_PROJECT_TOKENsecret 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.yamlaren't too restrictive - Set
COVDBG_LOG_LEVEL: DEBUGto 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/
See Also
- CLI Reference: complete command documentation
- Configuration: filter configuration with
.covdbg.yaml - Troubleshooting: common issues and solutions
- liasoft/covdbg-quick-start: official sample repository