Get started with coverage
Connect a repository, upload your first report, and see which changed lines need tests.
You’ll need access to install a GitHub App and edit your CI workflow. Supported reports: LCOV, Cobertura XML and JaCoCo XML.
On this page
1. Connect your repository
- Install the GitHub App for your account or organization and select the repositories to connect. Organization restrictions may require an administrator.
-
Sign in, open the organization or repository settings, and copy its upload token. Store it in GitHub Actions secrets as
COVERAGE_UPLOAD_TOKEN. Use a repository token for a single project; an organization token can serve multiple projects.
2. Generate and upload a report
Choose your test stack for report-generation commands and a working upload example.
Keep report paths relative to the checkout and upload coverage for the tested commit. Run the workflow on the default branch as well as pull requests so project checks have a matching-format baseline.
3. Put your coverage to work
Open the repository report and GitHub PR checks. Confirm the commit and baseline, inspect uncovered changed lines, add focused tests, and upload again. You can also connect a coding agent to read coverage context while you work locally.
- Install the Chrome extension for GitHub pull requestsSee exact-commit coverage on the Files changed page.
- Connect Codex or Claude with MCPAuthentication, configuration and available tools.
- Add a coverage badge to your READMEDefault-branch and branch-specific coverage.
Understand project and patch checks
Project coverage measures covered lines across the uploaded report. Its check passes when coverage is at least the baseline value; without a baseline it is neutral.
Patch coverage measures covered relevant changed lines divided by all relevant changed lines. The patch check requires 100%. For example, covering 8 of 10 relevant changed lines gives 80%, even if overall project coverage increased.
The baseline first uses a matching-format report for the supplied base SHA, then falls back to the latest matching-format base-branch report. The head commit is excluded. Inspect the recorded baseline rather than assuming it is the current default-branch head.
Coverage depends on the files and lines included by your test runner. Keep source inclusion and exclusion settings consistent. A green coverage check measures execution; it does not prove assertions are useful or that every behavior was tested.
Monorepositories
Ordinary repositories need no configuration and omit component. To opt in, commit
.9to5-coverage.json
at the repository root. Components describe independently measured, non-overlapping source subtrees; they need not match build-system modules. Names and dependencies are yours to choose.
{
"version": 1,
"components": {
"api": {"root": "services/api"},
"website": {"root": "apps/website", "path_prefix": "apps/website"}
}
}
This API/website layout is illustrative. IDs use lowercase letters, digits and hyphens. Each root is a repository-relative directory, without absolute paths, empty segments, traversal, backslashes or URL escapes. Roots cannot overlap. Optional
depends_on
lists other component IDs; dependencies must exist and cannot form cycles. Optional
path_prefix
is a literal directory prepended to every report path and defaults to an empty string. Unknown fields and duplicate identifiers are rejected.
Initial upload and partial workflows
The first configured commit needs a complete report for every component. Historical whole-repository reports are not component measurements. For the example above, upload the API report with repository-relative paths such as services/api/lib/app.ex. The website prefix turns
src/app.ts
into apps/website/src/app.ts. Generate reports from the repository root or configure the reporter's source paths; do not prepend a directory already present in the report.
curl --fail-with-body \
-H "Authorization: Bearer $COVERAGE_UPLOAD_TOKEN" \
-F "commit_sha=$(git rev-parse HEAD)" \
-F "branch=$BRANCH" \
-F "base_sha=$PR_BASE_SHA" \
-F "pull_request_number=$PR_NUMBER" \
-F "component=api" \
-F "coverage=@services/api/cover/lcov.info" \
https://coverage.9to5.software/api/v1/repos/OWNER/REPO/coverage
Replace OWNER/REPO and set the environment variables for your CI run. For branch uploads, omit the pull-request and base fields. Repeat for
website
with its complete report. LCOV uses SF:
paths; Cobertura uses class filename
paths. JaCoCo combines package and source-file names: com/example/App.kt
can use a prefix such as android/src/main/kotlin. Files outside the uploaded component are rejected. Supported formats can differ between components; the repository result has format composite.
Direct uploads return HTTP 200 and the aggregate result ID; while incomplete, project and patch percentages are null. Artifact requests use the same component field with the existing GitHub
artifact_url
or artifact_id
and optional coverage_path, and return HTTP 202 with upload/job IDs. Each upload replaces only its own component. A newer accepted upload takes precedence even if an older artifact job finishes later. Retry a failed component with a complete report.
Dependencies and carry-forward
{
"version": 1,
"components": {
"ios": {"root": "ios", "depends_on": ["shared"]},
"android": {"root": "android", "depends_on": ["shared"]},
"shared": {"root": "kotlin-shared-module"}
}
}
This mobile/shared-library setup is another example, not a reserved topology. Changing the shared component requires fresh reports for it and both dependants. Dependencies are transitive. Changing an independent API component can reuse an unchanged website measurement. Adding, editing, renaming or deleting any file under a component—including tests and build files—invalidates that component and its dependants. Changes outside all roots, including configuration and root documentation, invalidate every component. Do not skip dependant CI jobs when those components require fresh reports.
Carry-forward searches first-parent ancestry and verifies the complete source-to-target diff. An unrelated branch's latest report or a pull request base with coverage is not evidence for reuse. Merge commits follow their first parent; rebases require verification against the new ancestry. The source component definition must match. Verification examines at most 500 first-parent commits and accepts comparisons with fewer than 300 files; larger or truncated history/diffs and unavailable permissions remain incomplete. Upload fresh coverage if verification cannot finish. Carried forward means a previous measurement was reused; it does not mean tests ran on this commit. The original measurement ID, source SHA and time are retained even if that ancestor is uploaded again later.
Checks, troubleshooting and recovery
The existing 9to5 coverage / project
and 9to5 coverage / patch
checks remain in progress while components are missing or unverified; failed ingestion/configuration fails them. Missing coverage never becomes neutral or skipped. Once all components are ready, totals sum covered/relevant lines, not percentages. Patch coverage must be 100%. Project coverage must not regress against a complete, compatible result at the supplied PR base SHA. Without that baseline, project is neutral with “No comparable baseline”; completeness and patch requirements still apply. Existing test/build checks should remain independently required in branch protection.
The Components table separates Uploaded/Carried forward provenance from coverage outcomes and shows Waiting for upload, Upload failed or Unable to verify with corrective guidance. Select a component to filter files. Current incomplete badges display “incomplete”; MCP numerical reads return coverage_incomplete. Run versions change on replacement; refresh stale pinned reads before combining data.
Grant the GitHub App Contents read permission and subscribe it to push and pull-request events (opened, reopened, synchronize). Evaluation also runs when no report arrives. Invalid configuration/component/path responses use HTTP 422 with a stable code; configuration lookup failures use retryable HTTP 503, never ordinary-repository fallback. Check permissions, paths and dependencies, then retry. Removing the config explicitly returns later commits to ordinary behavior; stored composite results stay readable. Operators can disable new monorepo evaluation with the
:monorepo_enabled
application setting without reinterpreting configured uploads.
When an upload or check is missing
- Missing report
- Confirm the test runner wrote the exact upload path. Vitest needs an LCOV reporter; Gradle needs JaCoCo XML enabled.
- Missing baseline
- Upload the base commit or base branch using the same report format. For an exact comparison, ensure that the base SHA has a report.
- Fork pull requests
- GitHub normally withholds repository secrets from fork workflows. An unavailable upload token prevents authenticated upload. Do not expose tokens to untrusted code to work around this.
- Mismatched paths or multiple formats
- Generate reports from the checkout root and inspect reported file paths. MCP clients can select a format explicitly when multiple formats make the result ambiguous.
API reference
Current upload API
Use the reusable GitHub Action for GitHub Actions setup. The same endpoint also supports bearer-token multipart uploads for other CI providers and JSON artifact URL submissions for the Action.
Authentication
Send Authorization: Bearer COVERAGE_UPLOAD_TOKEN. Repository and organization tokens are supported.
Upload endpoint override
POST /api/v1/repos/:owner/:repo/coverage
The GitHub Action's endpoint input is optional and only needed when overriding the default upload host. Multipart fields: commit_sha, branch, and coverage or file.
Artifact JSON
JSON submissions use commit_sha, branch, artifact_url, and coverage_path. Artifact URLs must point to a GitHub Actions artifact for the same repository.
Optional fields
Include base_sha, base_branch, pull_request_number, and run_url for richer pull request reporting.
Success response
Multipart uploads return status, coverage_run_id, project and patch coverage percentages, and project/patch conclusions. Artifact JSON submissions return status: queued, upload_id, and job_id; processing status is visible on the repository page.
Error responses
400: commit SHA, branch, coverage file, or artifact URL is missing or invalid.
401: upload token is invalid for the requested repository.
422: the coverage file cannot be downloaded, found, parsed, or persisted.