# Data and Telemetry

- Section: Documentation > Reference > Data and Telemetry
- Canonical: https://covdbg.com/docs/reference/data-and-telemetry/

---

This page lists every moment covdbg talks to a server, what it sends, what we store, and how you turn off the parts that can be turned off. It is written from the client and service source code and is kept in step with them.

The short version: covdbg never sends your source code, file names, paths, or coverage data anywhere. It talks to our servers at three moments: when you sign in, when it checks whether a run is licensed, and, after a run, one small telemetry event that you can switch off.

## When covdbg talks to a server

| Moment | Where | What for |
|--------|-------|----------|
| `covdbg login` | `app.covdbg.com` | Signing you in, once per machine |
| Start of a run | `app.covdbg.com` | Asking whether this run is licensed |
| End of a run | `telemetry.covdbg.com` | One usage event; optional |

Nothing else. Instrumenting, tracing, and writing the coverage database happen entirely on your machine, and `covdbg convert`, `merge`, and `analyze` make no network requests at all.

## Signing in

`covdbg login` opens a page on app.covdbg.com in your browser and shows a short code. On that page you sign in with GitHub. covdbg itself never talks to GitHub; the browser does.

What we ask GitHub for is your numeric user id and the email addresses you have verified there (the `read:user` and `user:email` scopes). Nothing about your organizations or repositories. The id is how we recognize you when you sign in again; the addresses are how we match your commits to you.

When the sign-in completes, covdbg receives a session credential (it starts with `covdbg_cs_`). It is valid for one year, and it is stored in the Windows Credential Manager under the name `Liasoft/covdbg`, encrypted for your Windows account. It is never written to a file in the clear. On our side we keep only a hash of it, so a database leak would not hand out working sessions.

Every session signed in as you is listed on your profile at app.covdbg.com, with the name the client gave (`covdbg`), when it was created, and when it was last used. You can end any of them there. `covdbg logout` ends the session on the service and removes it from the machine. `covdbg whoami` tells you who a machine is signed in as.

If you have signed in before, you can also sign in by a link sent to one of your verified addresses. A link is only sent to an address that belongs to an existing account, and the response is the same either way, so the form cannot be used to find out who has an account.

## The license check

At the start of a run, covdbg needs to know whether the run is covered. It sends one request to `app.covdbg.com`:

| Field | Where it comes from | Why |
|-------|---------------------|-----|
| The git remote URL | `remote.origin.url` in the repository's `.git/config`, as written there | Tells the service which repository this is and whether it is public |
| The root commit hash | `git rev-list --max-parents=0 HEAD`, only when the repository has no remote | Names a repository that has no remote, so removing `origin` does not create a fresh allowance |
| Your commit email | `user.email` from the repository's git configuration, or your global git configuration if the repository sets none | In CI, this is the address a seat is matched to. For a signed-in local run the service ignores it |
| Your credential | Your session, or `COVDBG_PROJECT_TOKEN` in CI | Says who is asking |

That is the whole request. No source code, no file list, no path on your disk, no binary name, no coverage numbers.

A run with no credential is refused by covdbg itself before anything is sent. There is no anonymous run.

### What the service does with the remote

To decide whether a repository is public, the service asks the repository's host the same question every `git clone` asks: it requests `/info/refs?service=git-upload-pack` from the remote URL over HTTPS, with no credentials. A host that answers without asking for a login is public. The answer is cached for fifteen minutes. The probe follows no redirects, has a short timeout, and refuses to contact addresses that resolve to private networks, so it cannot be pointed at something inside your network. A host it cannot reach counts as private, which is the safe direction; an open source project on a private mirror can ask us for a grant.

### What the service keeps from a license check

Each answered request is recorded as a decision: the time, the normalized repository key (host, owner, and name, with the URL spelling and `.git` suffix removed), the commit email, whether the caller was a signed-in person or a project token, the decision, and the reason. That record is what your own dashboard and a team's adoption page are built from.

The repository itself is kept as a project row: the normalized key, whether it is public, and when that was last checked. An author a team's CI sees without a seat is kept as one row per team and address, with the repository they were last seen on and a run count, so an owner can invite them.

### What covdbg keeps on your machine

The service's answer is a signed token. covdbg verifies the signature against a key built into the binary and keeps the token in the Windows Credential Manager under `Liasoft/covdbg/entitlement/`, one per repository and credential. It is reused for seven days without asking again. If the service cannot be reached, the last answer keeps working for up to three weeks, and covdbg says so on the console. With a credential and nothing cached, the run goes ahead and tells you the service could not be asked.

The token contains the decision: which account it was attributed to, the reason, whether reports are allowed, and the two expiry times. It is not a secret and it can be read by anyone with access to your Windows account; it cannot be forged, because it is signed.

covdbg also writes a log file to `.covdbg\Logs\covdbg.log` next to your output, at DEBUG level by default. The log names the remote and the commit email it sent. It stays on your machine unless you attach it to a support request.

## Run telemetry

After the program you ran has exited, covdbg sends one event to `telemetry.covdbg.com`:

| Field | Example |
|-------|---------|
| covdbg version | `1.2.0` |
| Windows version | `Windows 11 (10.0.26200)` |
| How long the program ran | `1480` milliseconds |
| The program's exit code | `0` |

The request carries the entitlement token from the license check as its credential, which is how the event is attributed to you or your team. The service records those four fields together with the time, your account, the decision reason, and whether reports were allowed. It records nothing else: no repository, no path, no program name, no coverage.

Events are kept for 180 days and deleted by a sweep that runs every hour. They feed the runs-per-day chart on your own dashboard and the usage page an operator sees.

Telemetry never delays or fails a run. The event is sent in the background after the run is done; at exit covdbg waits at most two seconds for it and then leaves. A telemetry service that is slow, down, or answering with an error changes nothing about the run.

### Turning telemetry off

Either of these switches it off, and covdbg then sends no event at all:

```powershell
# in the environment
$env:COVDBG_TELEMETRY = "off"      # also: 0, false, no
```

```yaml
# in .covdbg.yaml
settings:
  telemetry: false
```

The environment variable wins over the file. There is no switch for the license check: a run always carries a credential and always asks, or reuses an answer it already has.

## Gated reports

When a team is over its seat count, or an author has run in a team's CI for more than ten days without a seat, runs still pass, but the report is gated: covdbg does the full analysis and keeps only the ten most-hit files in the coverage database. It says so on the console. Nothing about gating changes what is sent.

## Buying seats and email

Seats are bought at app.covdbg.com through Paddle, our merchant of record. Paddle collects your payment details and billing address; we never see your card. Paddle tells our service how many seats a team has paid for, and that is the only thing it sends us about the transaction.

We send email in two cases: an invitation to a seat, and a sign-in link you asked for. Both come from our automated notification address; use the [contact page](/company/contact/#email-addresses) if you need a reply.

## What we do not collect

- Source code, file names, paths, or the name of the program you ran
- Coverage data or any part of a report
- Your GitHub repositories, organizations, or anything beyond your id and verified addresses
- Crash reports from the client: a crash dump is written next to covdbg on your machine and stays there
- Analytics from the covdbg client beyond the telemetry event above

Our servers keep ordinary server logs of failed requests, which include the caller's IP address, so we can act on errors. They are not linked to runs or decisions.

## Air-gapped machines

A team that runs without any network access can ask us for an offline license file. It is a signed snapshot of the team's seats with an expiry date, verified by covdbg the same way an online answer is. Write to [our team](/company/contact/#email-addresses).

## Questions

If something here does not match what you observe, [contact our team](/company/contact/#email-addresses). The [privacy policy](/imprint/privacy/) covers your rights under the GDPR, and the [licensing FAQ](/docs/reference/licensing-faq/) explains how a run is decided.