API & badge¶
Upload¶
POST /api/v1/upload — multipart form, Authorization: Bearer <token>
| part | meaning |
|---|---|
profile |
file: the coverage profile |
repo |
optional; must match the token's repo |
commit |
required commit SHA |
branch |
defaults to the repo's default branch |
pr_id |
optional pull request id |
format |
go, lcov, jacoco, cobertura, clover or simplecov; omitted → detected from content |
path_prefix |
maps profile paths to repo paths for diff coverage, e.g. the Go module path (the CLI fills it from go.mod) |
part |
optional; names one slice of the commit's coverage (backend, frontend, e2e, …) uploaded from a separate CI job. Normalized to a lowercase slug ([a-z0-9._-], ≤64); omitted or blank → default. Re-uploading a part replaces it. See Parts |
Returns 201 with {id, total_pct, covered_stmts, total_stmts,
delta_pct, build_status}. Uploads carrying a pr_id additionally get
diff_pct, diff_covered_lines, diff_total_lines, diff_status and
pr_comment when the repo's workspace is connected to its forge.
Badge¶
Red below 50%, yellow 50–75%, green above 75%. Shows the latest upload on the repo's default branch. Badges are served without authentication even when web UI sign-in is enabled.
Health¶
GET /healthz reports readiness (checks database connectivity) for load balancers and container orchestrators; it stays
open when sign-in is enabled.
The container image is distroless, so it has no wget or curl for a Docker HEALTHCHECK to call. The binary probes
itself instead — gocov-server healthcheck requests /healthz on GOCOV_ADDR and exits non-zero if it is not 200 OK,
which is what the compose files use. Three timeouts are nested inside each other and want to stay in that order: the 2s
/healthz spends on its database ping, the 2.5s the probe waits for a reply, and the 3s Docker allows the probe to run.