# GitHub Actions

- Section: Documentation > Integrations > GitHub Actions
- Canonical: https://covdbg.com/docs/integrations/github-actions/

---

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

For a complete working example, see [liasoft/quick-start](https://github.com/liasoft/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:

```yaml
- 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`:

```yaml
- 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](/docs/use-cases/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:

```yaml
- 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](https://codecov.io) for reporting:

```yaml
- 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:

```yaml
- 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:

```yaml
- 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:

```yaml
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
4. 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:

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

## See Also

* [CLI Reference](/docs/reference/cli-reference/) - Complete command documentation
* [Configuration](/docs/reference/configuration/) - Filter configuration with `.covdbg.yaml`
* [Troubleshooting](/docs/reference/troubleshooting/) - Common issues and solutions
* [liasoft/quick-start](https://github.com/liasoft/quick-start) - Official sample repository