# Coverage uploads

Upload your CI's coverage reports for an exact commit with `proofline coverage upload`, so Proofline's coverage check can read them when CI is not GitHub Actions.

## Upload reports

In the CI job, after the tests have written their reports, run:

```sh
proofline coverage upload \
  --repository-id "$PROOFLINE_REPOSITORY_ID" \
  --commit "$TESTED_COMMIT_SHA" \
  --report coverage/lcov.info --json
```

| Option | Value |
| --- | --- |
| `--repository-id UUID` | The Proofline ID of the repository that receives the reports |
| `--commit SHA` | The full lowercase 40-character SHA of the commit the tests ran on |
| `--report FILE` | A report file. Repeat it for each report |
| `--json` | Print the recorded upload as JSON |

The CLI sends the SHA your CI supplies exactly as given. It resolves no branch and runs no tests. A branch, tag or abbreviated SHA, a commit GitHub does not have in the repository, or a report Proofline cannot read is refused with the reason, and nothing is stored.

## Token

Set `PROOFLINE_TOKEN` to a token restricted to the repository that holds `coverage:write`, and set `PROOFLINE_ORGANIZATION_ID` or pass `--org`. Only a token restricted to repositories can hold `coverage:write`, so a browser sign-in cannot upload. [Authentication](/docs/authentication/#tokens) says how to create a token.

Each upload checks that the token's holder has write access to the repository on GitHub at that moment, because a report can decide a check that blocks merging. A repository outside the token's restriction or organization is answered as not found.

## Reports

An upload reads LCOV, Cobertura XML, JaCoCo XML and Go cover profiles. Pass each file exactly as the tool wrote it, as UTF-8 text. An XML report that declares or references an entity is refused.

One upload holds up to 50 reports with distinct names, in a JSON body of at most 30 MiB that records at most 20,000,000 instrumented lines in all.

The CLI names each report by its path. A relative path keeps its directories, so `packages/a/lcov.info` and `packages/b/lcov.info` are two reports. A leading `./` is removed, and a relative path cannot contain `..`. An absolute path is named by its file name alone. A path that is not UTF-8, or that has a backslash or colon in any segment, is refused.

## What an upload records

Without `--json`, a successful upload prints one line:

```text
Coverage report REPORT_ID: COVERED of INSTRUMENTED instrumented lines covered; tested commit SHA.
```

The line counts cover all the reports, and a file that two reports name under one path is counted once. Uploading the same reports for the same commit again prints the report already recorded, followed by `These reports were already recorded.`

The text output does not say which format each report was read as. With `--json`, the CLI prints the upload receipt as one JSON object, and its `formats` field does:

| Field | Value |
| --- | --- |
| `report_id` | The ID of the recorded report |
| `tested_sha` | The commit, as the upload named it |
| `created` | `false` when the same reports for this commit were already recorded |
| `formats` | The format each report was read as, in the order of the `--report` options: `LCOV`, `COBERTURA`, `JACOCO` or `GO_PROFILE` |
| `instrumented_lines` | Instrumented lines across the reports, a file two reports name under one path counted once |
| `covered_lines` | Covered lines among those instrumented lines |

A job that must confirm a JaCoCo file was read as JaCoCo can test the receipt with `jq -e '.formats == ["JACOCO"]'`.

Proofline records the commit's parents with the report, so a report for a merge commit counts for a pull request head that is one of its two parents.

An upload records evidence and nothing more. It starts no review and publishes nothing, and the server evaluates the coverage check separately. The help center describes [how to set up a changed-line coverage check](/help/configure-changed-line-coverage/) that reads uploaded reports.

## The API request

The command sends one request to [Upload coverage reports](/docs/api/#upload-coverage-reports), `POST /api/v1/organizations/{org_id}/repositories/{repo_id}/coverage-reports`. Its body names the commit as `tested_sha` and holds each report's `name` and `content`. jq reads the report file and curl sends the JSON on standard input, so a large report never becomes a command-line argument:

```sh
jq -n --arg sha "$TESTED_COMMIT_SHA" --rawfile lcov coverage/lcov.info '{tested_sha: $sha, reports: [{name: "coverage/lcov.info", content: $lcov}]}' |
curl -sS -X POST "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/repositories/$PROOFLINE_REPOSITORY_ID/coverage-reports" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

A new report returns `201` with `created` true. The same reports for the same commit return `200` with the report already recorded.

## Upload a monorepo's reports with the SDKs

The [SDKs](/docs/sdks/) send the same request. Python's clients have `upload_coverage_reports`. TypeScript has `uploadCoverageReports`, and `uploadCoverageFiles`, which reads the report files from disk. Each returns the upload receipt, not a coverage check result.

A monorepo job often writes one report per package under the same file name. These examples upload `packages/api/coverage/lcov.info` and `packages/web/coverage/lcov.info` for the tested commit in one request, and each report's name keeps its package's directories:

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const receipt = await client.uploadCoverageFiles(
  {
    path: {
      org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
      repo_id: process.env.PROOFLINE_REPOSITORY_ID!,
    },
  },
  {
    tested_sha: process.env.TESTED_COMMIT_SHA!,
    files: ["packages/api/coverage/lcov.info", "packages/web/coverage/lcov.info"],
  },
);
if (receipt.formats.some((format) => format !== "LCOV")) {
  throw new Error(`expected LCOV reports, read ${receipt.formats.join(", ")}`);
}
const outcome = receipt.created ? "Recorded" : "Already recorded";
console.log(`${outcome} coverage report ${receipt.report_id} for ${receipt.tested_sha}`);
```

```python
import os
from pathlib import Path
from uuid import UUID
from proofline import CoverageUploadRequest, ProoflineClient, UploadedReport

paths = ["packages/api/coverage/lcov.info", "packages/web/coverage/lcov.info"]
# read_bytes keeps each report's line endings, which read_text would translate.
reports = [
    UploadedReport(name=path, content=Path(path).read_bytes().decode("utf-8"))
    for path in paths
]
with ProoflineClient(os.environ["PROOFLINE_TOKEN"], base_url="https://proofline.sh") as client:
    receipt = client.upload_coverage_reports(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["PROOFLINE_REPOSITORY_ID"]),
        body=CoverageUploadRequest(
            tested_sha=os.environ["TESTED_COMMIT_SHA"], reports=reports
        ),
    )
if any(kind != "LCOV" for kind in receipt.formats):
    raise SystemExit(f"expected LCOV reports, read {', '.join(receipt.formats)}")
outcome = "Recorded" if receipt.created else "Already recorded"
print(f"{outcome} coverage report {receipt.report_id} for {receipt.tested_sha}")
```

`uploadCoverageFiles` resolves each path against `root`, which defaults to the working directory, and names the report by its path relative to `root`, with `/` between directories. Run from the repository's root, the TypeScript example sends the names `packages/api/coverage/lcov.info` and `packages/web/coverage/lcov.info`. A job that runs in another directory sets `root` to the repository's checkout. To send a different name, pass `{ path, name }` in place of the path; a report outside `root` needs one. A name must be a relative path with no empty, `.` or `..` segment and no backslash. Python sends the names you give it, so name each report by its path from the repository's root.

Each report's content is the file's text exactly as the tool wrote it. `uploadCoverageFiles` refuses a file that is not UTF-8, and refuses before sending anything what the server would also refuse: an abbreviated SHA, more than 50 reports, two reports with one name, or a body over 30 MiB.

The receipt lists the format each report was read as, in the order of the files, and the examples stop when a report was not read as LCOV. `created` is `false` when the same reports for this commit were already recorded, so a retried job prints the report it recorded the first time. The receipt says what Proofline recorded and nothing about whether the coverage check passes, which the server evaluates separately.
