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:
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 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:
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 that reads uploaded reports.
The API request#
The command sends one request to 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:
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 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:
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}`);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.