{"id":"4db9ceae-23aa-429c-8970-6a96eab4fbb7","slug":"opencoverage","kind":"mcp","name":"opencoverage","summary":"Self-hosted coverage API + dashboard for ingesting CI reports and tracking coverage deltas over time.","owner":"arxdsilva","repoUrl":"https://github.com/arxdsilva/opencoverage","license":"MIT","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-28T22:44:45.000Z","addedAt":"2026-10-21T08:35:55.060Z","logoUrl":"https://avatars.githubusercontent.com/u/9372503?u=663afec47e6a403530f4298cfabbfe3aac583ece&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","data-analytics"],"tags":["actions","api","ci","cicd","code-coverage","coverage","github","go"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T08:38:28.680Z","sample":false,"url":"https://conduits.dev/tools/opencoverage","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# coverage-api\n\n[![CI](https://github.com/arxdsilva/opencoverage/actions/workflows/ci.yml/badge.svg)](https://github.com/arxdsilva/opencoverage/actions/workflows/ci.yml)\n\n## Dashboard Preview\n\n![OpenCoverage dashboard preview 1](imgs/opencov-1.png)\n![OpenCoverage dashboard preview 2](imgs/opencov-2.png)\n![OpenCoverage dashboard preview 2](imgs/opencov-3.png)\n![OpenCoverage dashboard preview 2](imgs/opencov-4.png)\n\nSelf-hosted Go code coverage API and dashboard for ingesting test coverage, comparing deltas, and tracking trends across projects, branches, and teams.\n\n`coverage-api` is part of the `opencoverage` project and is designed for developer teams that want coverage visibility in their own infrastructure.\n\n## Why coverage-api\n\n- Ingest Go coverage results from local runs or CI pipelines\n- Compute deterministic baseline comparisons and deltas\n- Track project and package-level coverage history\n- Group projects (for team-level reporting)\n- Integrate with GitHub Actions and other CI systems\n- Self-host API + frontend with PostgreSQL\n\n## Key Features\n\n- REST API with `/v1` endpoints for ingest, history, and latest comparison\n- Coverage CLI to convert `coverage.out` into API-ready JSON payloads\n- Dashboard frontend for project, multi-branch trend, comparison, and heatmap visualization\n- Integration test result ingestion and heatmap visualization\n- API key authentication for protected endpoints\n- Hexagonal Architecture (ports and adapters)\n\n## Quick Start (Docker Compose)\n\nRun the full local stack (PostgreSQL + API + seed + frontend + MCP):\n\n```bash\nmake compose-up\n```\n\nIf local port `5432` is already in use:\n\n```bash\nDB_PORT=5433 make compose-up\n```\n\nAccess services:\n\n- API: `http://localhost:8080`\n- Frontend dashboard: `http://localhost:8090`\n- Health check: `http://localhost:8080/healthz`\n\nCompose startup behavior:\n\n1. `db` starts first and must pass its healthcheck.\n2. `api` starts next and runs all DB migrations during startup.\n3. `api` exposes `/healthz` only after startup completes.\n4. `seed` runs only after `api` is healthy.\n5. `mcp` starts after `seed` completes successfully.\n\nStop the stack:\n\n```bash\nmake compose-down\n```\n\n## Local Development\n\nRequirements:\n\n- Go 1.23+\n- PostgreSQL 14+\n\nCore environment variables:\n\n- `DATABASE_URL` (required)\n- `MIGRATIONS_DIR` (default `./migrations`, used by API startup migrations)\n- `API_KEY_SECRET` (required)\n- `SERVER_ADDR` (default `:8080`)\n- `API_KEY_HEADER` (default `X-API-Key`)\n- `SHUTDOWN_TIMEOUT_SECONDS` (default `10`)\n\nRun API locally:\n\n```bash\nexport DATABASE_URL=\"postgres://coverage:coverage@localhost:5432/coverage?sslmode=disable\"\nexport API_KEY_SECRET=\"dev-local-key\"\ngo run ./cmd/api\n```\n\n`cmd/api` runs migrations on startup before serving HTTP traffic.\n\nRun MCP server locally:\n\n```bash\nexport DATABASE_URL=\"postgres://coverage:coverage@localhost:5432/coverage?sslmode=disable\"\nexport MCP_SERVER_NAME=\"opencoverage\"\nexport MCP_SERVER_VERSION=\"dev\"\ngo run ./cmd/mcp\n```\n\n`cmd/mcp` does not run migrations. Start the API first (or run `make migrate-up`) before starting MCP against a fresh database.\n\nOptional MCP settings:\n\n- `MCP_TRANSPORT` (default `stdio`)\n- `MCP_ENABLE_PROMPTS` (default `true`)\n- `MCP_LOG_LEVEL` (default `info`) - MCP server log verbosity (for example: `debug`, `info`, `warn`, `error`).\n- `MCP_ENABLE_WRITE_TOOLS` (default `false`) - enables `ingest_coverage_run` and `ingest_integration_run`; write tools require a transport that can carry request headers and a non-empty `API_KEY_SECRET` in your shell or deployment environment (for example `export API_KEY_SECRET=\"dev-local-key\"`) before starting `go run ./cmd/mcp`.\n- `MCP_MAX_PAGE_SIZE` (default `100`)\n- `MCP_DEFAULT_RUNS_LIMIT` (default `20`)\n\nRun frontend locally:\n\n```bash\nmake frontend-run\n```\n\nUseful developer commands:\n\n```bash\nmake deps\nmake fmt\nmake test\nmake migrate-status\nmake migrate-up\n```\n\n## API Overview\n\nMain endpoints:\n\n- `GET /v1/projects`\n- `POST /v1/coverage-runs`\n- `GET /v1/projects/{projectId}`\n- `GET /v1/projects/{projectId}/coverage-runs`\n- `GET /v1/projects/{projectId}/coverage-runs/latest-comparison`\n- `GET /v1/projects/{projectId}/branches`\n- `GET /v1/projects/{projectId}/contributors`\n- `POST /v1/integration-test-runs`\n- `GET /v1/integration-test-runs/heatmap`\n- `GET /v1/projects/{projectId}/integration-test-runs`\n- `GET /v1/projects/{projectId}/integration-test-runs/latest-comparison`\n- `GET /v1/projects/{projectId}/integration-test-runs/{runId}`\n\nFor full API contract details, see [SPEC.md](SPEC.md).\n\n## Ingest Coverage With cURL\n\nSet variables:\n\n```bash\nexport BASE_URL=\"http://localhost:8080\"\nexport API_KEY=\"dev-local-key\"\n```\n\nSend a coverage run:\n\n```bash\ncurl -i -X POST \"$BASE_URL/v1/coverage-runs\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: $API_KEY\" \\\n  -d '{\n    \"projectKey\": \"org/repo-service\",\n    \"projectName\": \"repo-service\",\n    \"projectGroup\": \"platform-team\",\n    \"defaultBranch\": \"main\",\n    \"branch\": \"main\",\n    \"commitSha\": \"a1b2c3d4\",\n    \"author\": \"alice\",\n    \"triggerType\": \"push\",\n    \"runTimestamp\": \"2026-03-28T12:00:00Z\",\n    \"totalCoveragePercent\": 83.42,\n    \"packages\": [\n      {\"importPath\": \"github.com/acme/repo-service/internal/api\", \"coveragePercent\": 85.10},\n      {\"importPath\": \"github.com/acme/repo-service/internal/service\", \"coveragePercent\": 80.70}\n    ]\n  }'\n```\n\n## Coverage CLI Workflow\n\nGenerate payload from Go coverage profile:\n\n```bash\ngo run ./cmd/coveragecli \\\n  -coverprofile coverage.out \\\n  -out coverage-upload.json \\\n  -project-key \"github.com/example/repo\" \\\n  -project-name \"repo\" \\\n  -project-group \"platform\" \\\n  -default-branch \"main\" \\\n  -branch \"main\" \\\n  -commit-sha \"abc123\" \\\n  -author \"alice\"\n```\n\nGenerate and upload in one command:\n\n```bash\nmake coverage-upload API_URL=\"http://localhost:8080/v1/coverage-runs\" API_KEY=\"dev-local-key\"\n```\n\nInstall CLI from GitHub:\n\n```bash\ngo install github.com/arxdsilva/opencoverage/cmd/coveragecli@latest\n```\n\n### Upload Vitest Coverage Summary (npm)\n\nGenerate Vitest coverage summary:\n\n```bash\nnpx vitest run --coverage --coverage.reporter=lcov --coverage.reporter=json-summary\n```\n\nUpload `coverage/coverage-summary.json` using the CLI:\n\n```bash\ngo run ./cmd/coveragecli npm-upload \\\n  -vitest-summary coverage/coverage-summary.json \\\n  -api-url http://localhost:8080/v1/coverage-runs \\\n  -api-key dev-local-key \\\n  -project-key github.com/example/frontend-repo \\\n  -project-name frontend-repo \\\n  -project-group frontend \\\n  -default-branch main \\\n  -branch main \\\n  -commit-sha abc123 \\\n  -author alice \\\n  -trigger-type push\n```\n\nUseful options:\n\n- `-metric lines|statements|functions|branches` (default `lines`)\n- `-group-by dir|file` (default `dir`)\n- `-include-glob` and `-exclude-glob` (repeatable)\n- `-path-strip-prefix` for deterministic path normalization\n- `-dry-run` and `-out <payload.json>` to inspect payload without upload\n\n## Architecture\n\nThis project follows Hexagonal Architecture (ports and adapters):\n\n- `cmd/api` - bootstrap and dependency wiring\n- `internal/domain` - entities, invariants, deterministic domain logic\n- `internal/application` - use cases and ports\n- `internal/adapters/http` - handlers, DTOs, middleware\n- `internal/adapters/postgres` - repository implementations\n- `internal/adapters/auth` - API key authentication adapter\n- `internal/platform` - config and infrastructure utilities\n\n## Database and Migrations\n\nMigration files are in `migrations/`.\n\nMigration ownership:\n\n1. API process owns automatic migration execution at startup.\n2. MCP and frontend processes never run migrations.\n3. In Docker Compose, `seed` waits for API health so seeding happens after migrations.\n\nCommon commands:\n\n```bash\nmake migrate-status\nmake migrate-up\nmake migrate-down\nmake migrate-create name=add_new_table\n```\n\nSeed local database:\n\n```bash\nmake seed\n```\n\n## CI/CD and GitHub Actions\n\nFor complete CI examples (unit tests, `coverage.out`, CLI payload generation, upload to self-hosted API), see [GITHUB_ACTIONS_INTEGRATION.md](GITHUB_ACTIONS_INTEGRATION.md).\n\nThe examples include:\n\n- Configurable project metadata (`project key`, `name`, `group`)\n- Push and pull request workflows\n- Multi-project matrix workflows for monorepos\n- PR comments and threshold-based quality gates\n\n## Frontend and Product Docs\n\n- Frontend behavior and UI notes: [frontend.md](frontend.md)\n- API contract and response model: [SPEC.md](SPEC.md)\n- Contribution/PR workflow: [making-a-PR.md](making-a-PR.md)\n\nFrontend highlights:\n\n- Project overview includes a multi-branch coverage trend chart.\n- The trend view overlays the default branch with all discovered branches for the selected project.\n- The branch selector is used for latest-comparison details, not for filtering the trend chart.\n- Heatmap overlay shows all projects grouped by team, with tiles color-coded on a -3% to +3% delta scale (green = improved, red = regressed). A scale legend is displayed in the overlay header.\n- Top Contributors overlay shows the leading commit contributors per project across all teams, grouped the same way as the heatmap.\n- Integration Tests screen provides per-project integration test run history and failed spec details.\n- Integration Run Chain is rendered oldest to newest (newest on the right) and shows up to 5 runs.\n- Integration Pass Rate card shows run success ratio percentage computed as `passed runs / failed runs * 100` over the returned run-list window (up to last 20 runs).\n- Integration Heatmap shows all projects grouped by team but displays default-branch runs only, with `✅`/`❌` run markers and newest-run status tint per project row.\n- Integration Tests sidebar now supports group-first project navigation: filter by project group, then select a project from the filtered list (combined with project search).\n\n## Typical Integration Flow\n\n1. Run tests and produce `coverage.out`.\n2. Convert coverage profile to JSON payload with `coveragecli`.\n3. Upload payload to `POST /v1/coverage-runs`.\n4. Read comparison metadata (`thresholdStatus`, `deltaPercent`) in CI.\n5. Visualize trends and project groups in the dashboard.\n"}