README
¶
gocov
Hosted: gocov.dev — public repos free forever, badge included. Or self-host the whole thing (below); it's the same product.
Self-hostable coverage tracking — an open-source Coveralls/Codecov alternative. Single binary + Postgres.
- Forges: Bitbucket Cloud, GitHub and GitLab — build statuses, PR/MR comments with diff coverage, Bitbucket Code Insights report cards and GitHub check runs with inline annotations on uncovered changed lines
- Formats: Go cover profiles, LCOV (Jest, Vitest, nyc, c8), JaCoCo XML (Maven, Gradle, Android), Cobertura XML (coverage.py/pytest-cov, coverlet, gcovr), Clover XML (PHPUnit, Istanbul) and SimpleCov resultsets (Ruby) — detected from the uploaded content, no flag needed
- Coverage gate: per-repo minimums for total and diff coverage plus a drop tolerance; a failed gate pushes a FAILED status your forge's merge checks can block on
- Web UI: repo list, per-file coverage, line-by-line source view with hit counts, coverage trend chart, SVG badge per repo, sign-in with your forge account
The full tour, screenshots included, is in docs/features.md.
Quick start
docker compose up
This starts Postgres and the server on http://localhost:8080 (migrations apply automatically). Then, in the web UI:
- Enable sign-in with your forge and sign in — the onboarding wizard registers your workspace
(org/group/user) and shows its upload token, once. A brand-new instance tracks no workspaces yet, so set
GOCOV_ALLOWED_WORKSPACESto the one you want to track (e.g.GOCOV_ALLOWED_WORKSPACES=myorg) or every sign-in is denied. - Set
GOCOV_TOKEN(secured) andGOCOV_SERVERas workspace variables in CI; repos register themselves on their first upload. - Optionally connect the workspace to its forge — one click — for statuses, PR comments, check runs and diff coverage.
Upload from CI (GitHub Actions shown; Bitbucket Pipelines and GitLab CI here):
- run: npx jest --coverage # or go test -coverprofile, mvn verify, pytest --cov, ...
- uses: gocov/gocov-action@v1
with:
files: coverage/lcov.info
token: ${{ secrets.GOCOV_TOKEN }}
The action downloads the CLI binary and checks its sha256, so there is no toolchain to install — the same three lines
work whatever your tests are written in. Every supported format uploads this way; point files at whatever your test
runner produced. The badge is one line of markdown:
Documentation
Everything else lives in docs/:
- Getting started — onboarding, workspace settings, hosted mode
- Sign-in — OAuth setup for Bitbucket, GitHub, GitLab and the access model
- Forge connections — GitHub App and Bitbucket/GitLab one-click connect
- Uploading from CI — all three CIs, prebuilt binaries, other ecosystems
- Coverage gate · Parts · API & badge · Configuration · Development
License
AGPL-3.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gocov
command
gocov is the coverage uploader CLI, run inside CI:
|
gocov is the coverage uploader CLI, run inside CI: |
|
gocov-preview
command
Command gocov-preview is a throwaway dev harness: it serves the web UI from an in-memory store seeded with a synthetic upload history, for eyeballing UI changes without Postgres.
|
Command gocov-preview is a throwaway dev harness: it serves the web UI from an in-memory store seeded with a synthetic upload history, for eyeballing UI changes without Postgres. |
|
gocov-server
command
gocov-server runs the gocov API + web UI:
|
gocov-server runs the gocov API + web UI: |
|
internal
|
|
|
auth
Package auth defines the sign-in provider seam for the web UI.
|
Package auth defines the sign-in provider seam for the web UI. |
|
auth/bitbucket
Package bitbucket implements auth.Provider for Bitbucket Cloud using only the standard library.
|
Package bitbucket implements auth.Provider for Bitbucket Cloud using only the standard library. |
|
auth/github
Package github implements auth.Provider for GitHub (cloud github.com) using only the standard library.
|
Package github implements auth.Provider for GitHub (cloud github.com) using only the standard library. |
|
auth/gitlab
Package gitlab implements auth.Provider for GitLab (gitlab.com) using only the standard library.
|
Package gitlab implements auth.Provider for GitLab (gitlab.com) using only the standard library. |
|
blobstore
Package blobstore abstracts raw-profile persistence so it can later move to object storage (S3/R2) without touching callers.
|
Package blobstore abstracts raw-profile persistence so it can later move to object storage (S3/R2) without touching callers. |
|
blobstore/memory
Package memory provides an in-memory blobstore.Store for tests.
|
Package memory provides an in-memory blobstore.Store for tests. |
|
blobstore/postgres
Package postgres implements blobstore.Store on a Postgres bytea column.
|
Package postgres implements blobstore.Store on a Postgres bytea column. |
|
config
Package config declares every environment variable the gocov binaries read.
|
Package config declares every environment variable the gocov binaries read. |
|
core
Package core is gocov's coverage logic, with no HTTP in it.
|
Package core is gocov's coverage logic, with no HTTP in it. |
|
diffcov
Package diffcov computes diff coverage: which changed lines of a pull request are covered by tests.
|
Package diffcov computes diff coverage: which changed lines of a pull request are covered by tests. |
|
forge
Package forge abstracts VCS-host integrations (Bitbucket first; GitHub and GitLab later).
|
Package forge abstracts VCS-host integrations (Bitbucket first; GitHub and GitLab later). |
|
forge/bitbucket
Package bitbucket implements forge.Forge for Bitbucket Cloud.
|
Package bitbucket implements forge.Forge for Bitbucket Cloud. |
|
forge/fake
Package fake provides a recording forge.Forge test double.
|
Package fake provides a recording forge.Forge test double. |
|
forge/github
Package github implements forge.Forge for GitHub (cloud github.com).
|
Package github implements forge.Forge for GitHub (cloud github.com). |
|
forge/gitlab
Package gitlab implements forge.Forge for GitLab (gitlab.com; a self-managed instance works through BaseURL but is not yet officially supported).
|
Package gitlab implements forge.Forge for GitLab (gitlab.com; a self-managed instance works through BaseURL but is not yet officially supported). |
|
hosted
Package hosted holds shared constants for the hosted gocov service, so the CLI's default server and the onboarding page's "server is implicit" check stay in sync from a single source of truth.
|
Package hosted holds shared constants for the hosted gocov service, so the CLI's default server and the onboarding page's "server is implicit" check stay in sync from a single source of truth. |
|
profile
Package profile defines the normalized coverage model shared by every coverage format, and the Parser interface that format-specific parsers implement.
|
Package profile defines the normalized coverage model shared by every coverage format, and the Parser interface that format-specific parsers implement. |
|
secretbox
Package secretbox seals short secrets for at-rest storage with AES-256-GCM (One-Click Connect D6).
|
Package secretbox seals short secrets for at-rest storage with AES-256-GCM (One-Click Connect D6). |
|
server
Package server implements the gocov HTTP API, badge endpoint and web UI.
|
Package server implements the gocov HTTP API, badge endpoint and web UI. |
|
store
Package store defines the storage interface and its domain types.
|
Package store defines the storage interface and its domain types. |
|
store/memory
Package memory provides an in-memory store.Store for tests.
|
Package memory provides an in-memory store.Store for tests. |
|
store/postgres
Package postgres implements store.Store on PostgreSQL via pgx.
|
Package postgres implements store.Store on PostgreSQL via pgx. |
|
testpg
Package testpg provides disposable Postgres databases for integration tests.
|
Package testpg provides disposable Postgres databases for integration tests. |
Click to show internal directories.
Click to hide internal directories.