📊 go-coverage

Your Coverage. Your Infrastructure. Pure Go.

`CI / CD`		`Quality`
`Security`		`Community`

`Project Navigation`

⚡ `Installation`	🧪 `Examples & Tests`	📚 `Documentation`
🤝 `Contributing`	🛠️ `Code Standards`	⚡ `Performance`
🤖 `AI Usage`	📝 `License`	👥 `Maintainers`

⚡ Quickstart

Go Coverage is a complete replacement for Codecov that runs entirely in your CI/CD pipeline with zero external dependencies. Get coverage reports, badges, and dashboards deployed to GitHub Pages automatically.

Installation

Go Coverage requires a supported release of Go.

Install CLI Tool (recommended):

go install github.com/mrz1836/go-coverage/cmd/go-coverage@latest

Or install go-coverage as a Library:

go get -u github.com/mrz1836/go-coverage

Verify Installation:

go-coverage --version
# go-coverage version v1.0...

Upgrade to Latest Version:

# Check for available updates
go-coverage upgrade --check

# Upgrade to the latest version
go-coverage upgrade

# Force reinstall even if already on latest
go-coverage upgrade --force

Development Setup

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install

Choose Your Coverage System

Option 1: Internal Coverage System (GitHub Pages) - Recommended

Set up GitHub Pages environment for coverage deployment:

go-coverage setup-pages

Option 2: External Coverage System (Codecov)

Create .github/.env.custom with:

GO_COVERAGE_PROVIDER=codecov
CODECOV_TOKEN_REQUIRED=true

Next, deploy to your main branch and generate coverage reports!

Core Features

🏷️ SVG Badge Generation – Custom badges with themes and logos
📊 HTML Reports & Dashboards – Beautiful, responsive coverage visualizations
📈 History & Trends – Track coverage changes over time
🤖 GitHub Integration – PR comments, commit statuses, automated deployments
🚀 GitHub Pages – Automated deployment with zero configuration
🔧 Highly Configurable – Thresholds, exclusions, templates, and more
⬆️ Auto-Upgrade – Built-in upgrade command for easy updates

🚀 GitHub Pages Setup

Automatic Deployment: Go Coverage automatically deploys coverage reports, badges, and dashboards to GitHub Pages with zero configuration.

Quick Setup

Set up GitHub Pages environment using the integrated CLI command:

# Auto-detect repository from git remote
go-coverage setup-pages

# Or specify repository explicitly
go-coverage setup-pages owner/repo

# Preview changes without making them
go-coverage setup-pages --dry-run

# Use a custom domain for GitHub Pages
go-coverage setup-pages --custom-domain mysite.com

This configures:

✅ GitHub Pages Environment with proper branch policies
✅ Deployment Permissions for master, gh-pages, and any */*/*/*/*/* branches
✅ Environment Protection rules for secure deployments

What Gets Deployed

Your coverage system automatically creates:

https://yourname.github.io/yourrepo/
├── coverage.svg              # Live coverage badge
├── index.html                # Coverage dashboard
├── coverage.html             # Detailed coverage report
└── reports/branch/master/    # Branch-specific reports

Manual GitHub Pages Configuration

If the setup command fails, manually configure:

Go to Settings → Environments → github-pages
Under Deployment branches, select "Selected branches and tags"
Add these deployment branch rules:
- master (main deployments)
- gh-pages (GitHub Pages default)
- *, */*, */*/*, */*/*/*, */*/*/*/*, */*/*/*/*/* (all branches for PR-specific reports)
Save changes and verify in workflow runs

Integration with CI/CD

The coverage system integrates with your existing GitHub Actions:

# In your .github/workflows/ci.yml
- name: Generate Coverage Report
  run: |
    go test -coverprofile=coverage.txt ./...
    go-coverage complete -i coverage.txt

🎯 Starting a New Project

1. Install the CLI Tool

go install github.com/mrz1836/go-coverage/cmd/go-coverage@latest

2. Configure GitHub Pages

# Use the integrated command (requires gh CLI)
go-coverage setup-pages

3. Add to GitHub Actions

Add coverage generation to your workflow:

name: Coverage
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Run Tests with Coverage
        run: go test -coverprofile=coverage.txt ./...

      - name: Generate Coverage Reports
        run: go-coverage complete -i coverage.txt -o coverage
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./coverage

4. First Run

Commit and push - your coverage reports will be available at:

Reports: https://yourname.github.io/yourrepo/
Badge: https://yourname.github.io/yourrepo/coverage.svg

Advanced Configuration

Create a .go-coverage.json config file:

{
  "coverage": {
    "threshold": 80.0,
    "exclude_paths": ["vendor/", "test/"],
    "exclude_files": ["*.pb.go", "*_gen.go"]
  },
  "badge": {
    "style": "flat",
    "logo": "go"
  },
  "report": {
    "title": "My Project Coverage",
    "theme": "dark"
  },
  "history": {
    "enabled": true,
    "retention_days": 90
  }
}

📚 Documentation

Quick Start Guides

⚡ Quickstart – Get started in 5 minutes with installation and basic setup
📚 User Guide – Complete usage guide with examples and workflows

Reference Documentation

🛠️ CLI Reference – Detailed command-line reference and options
⚙️ Configuration – Environment variables and configuration options
CLI Reference – Complete command documentation at pkg.go.dev/github.com/mrz1836/go-coverage

Developer Resources

🤝 Contributing – How to contribute code, tests, and documentation
🏗️ Architecture – Technical architecture and design decisions

Features Overview

Coverage Analysis – Parse Go coverage profiles with exclusions and thresholds
Badge Generation – Create SVG badges with custom styling and themes
Report Generation – Build HTML dashboards and detailed coverage reports
History Tracking – Monitor coverage trends over time with retention policies
GitHub Integration – PR comments, commit statuses, and automated deployments

Go Coverage Features

Zero External Dependencies – Complete coverage system that runs entirely in your CI/CD pipeline with no third-party services required.
GitHub Pages Integration – Automatic deployment of coverage reports, badges, and dashboards with branch-specific and PR-specific deployments.
Advanced Coverage Analysis – Parse Go coverage profiles with support for path exclusions, file pattern exclusions, and threshold enforcement.
Professional Badge Generation – SVG coverage badges with customizable styles, colors, logos, and themes that update automatically.
Rich HTML Reports – Beautiful, responsive coverage dashboards with detailed file-level analysis and interactive visualizations.
Coverage History & Trends – Track coverage changes over time with retention policies, trend analysis, and historical comparisons.
Smart GitHub Integration – Automated PR comments with coverage analysis, commit status checks, and diff-based coverage reporting.
Multi-Branch Support – Separate coverage tracking for different branches with automatic main branch detection and PR context handling.
Comprehensive CLI Tool – Six powerful commands (complete, comment, parse, history, setup-pages, upgrade) for all coverage operations.
Highly Configurable – JSON-based configuration for thresholds, exclusions, badge styling, report themes, and integration settings.
Enterprise Ready – Built with security, performance, and scalability in mind for production environments.
Self-Contained Deployment – Everything runs in your repository's .github folder with no external service dependencies or accounts required.

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by a flexible two-file configuration system – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

.env.base – Default configuration that works for most Go projects
.env.custom – Optional project-specific overrides

This powerful system controls everything from:

🚀 Go version matrix (test on multiple versions or just one)
🏃 Runner selection (Ubuntu or macOS, your wallet decides)
🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
🛡️ Security tool versions (gitleaks, nancy, govulncheck)
🤖 Auto-merge behaviors (how aggressive should the bots be?)
🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Create .env.custom with ENABLE_CODE_COVERAGE=false and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the Go Coverage security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at `.github/labels.yml`.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🔧 Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via .env.base and can be customized using also using .env.custom and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

🧪 Examples & Tests

The Go Coverage system is thoroughly tested via GitHub Actions and uses Go version 1.24.x. View the configuration file.

CLI Command Examples

# Complete coverage pipeline (parse + badge + report + history + GitHub)
go-coverage complete -i coverage.txt -o coverage-reports

# Generate PR comment with coverage analysis
go-coverage comment --pr 123 --coverage coverage.txt --base-coverage base-coverage.txt

# Parse coverage data with exclusions
go-coverage parse -i coverage.txt --exclude-paths "vendor/,test/" --threshold 80

# View coverage history and trends
go-coverage history --branch master --days 30 --format json

# Set up GitHub Pages environment for coverage deployment
go-coverage setup-pages --verbose --dry-run
go-coverage setup-pages owner/repo --custom-domain example.com

# Upgrade to the latest version
go-coverage upgrade --check
go-coverage upgrade --force --verbose

Testing the Coverage System

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

🔬 Fuzz Testing

The coverage system includes comprehensive fuzz tests for critical functions to ensure robustness and security:

Available Fuzz Tests

Package	Functions Tested	Coverage	Security Focus
urlutil	URL building, path cleaning	100%	Path traversal, XSS prevention
badge	Badge generation, color selection	97.7%	SVG injection, encoding
parser	Coverage parsing, file exclusion	84.1%	Malformed input handling

Running Fuzz Tests

# Run specific fuzz tests
go test -fuzz=FuzzBuildGitHubCommitURL -fuzztime=10s ./internal/urlutil/
go test -fuzz=FuzzGetColorForPercentage -fuzztime=10s ./internal/badge/
go test -fuzz=FuzzParseStatementSimple -fuzztime=10s ./internal/parser/

# Run all fuzz tests (via MAGE-X)
magex test-fuzz

Fuzz Test Features

✅ Comprehensive Input Coverage: Valid inputs, edge cases, malformed data
✅ Security Testing: Path traversal, XSS, injection attempts, null bytes
✅ Panic Prevention: Never panics on any input
✅ Unicode Support: Proper UTF-8 handling and validation
✅ Performance Testing: Long inputs, memory efficiency

Example Output

The system generates comprehensive coverage reports:

📊 Coverage Dashboard: https://yourname.github.io/yourrepo/
🏷️ Coverage Badge: https://yourname.github.io/yourrepo/coverage.svg
📈 Coverage: 87.4% (1,247/1,426 lines)
📦 Packages: 15 analyzed
🔍 Trend: UP (+2.3% from last run)

⚡ Performance

The Go Coverage system is optimized for speed and efficiency in CI/CD environments.

magex bench

⚡ Benchmark Results & Performance Metrics

Benchmark Results

Component	Operation	Time/op	Memory/op	Allocs/op	Description
Parser	Parse (100 files)	105.9ns	8B	0	Parse coverage data with 100 files
Parser	Parse (1000 files)	14.4ms	8.0MB	106,870	Large coverage files
Badge	Generate SVG	1.76µs	2.5KB	14	Badge generation
Badge	Generate with Logo	1.82µs	2.7KB	15	Badge with custom logo
Dashboard	Generate HTML	12.3ms	1.4MB	10,645	Full dashboard generation
Report	Generate Report	8.17ms	1.1MB	7,890	Coverage report generation
History	Record Entry	240µs	9.2KB	68	Store coverage entry
History	Get Trend (30 days)	1.7ms	255KB	1,254	Trend analysis
Analysis	Compare Coverage	20.4µs	42KB	146	Coverage comparison
Templates	Render PR Comment	38.9µs	11KB	377	Comment generation
URL	Build GitHub URL	50.1ns	48B	1	URL construction

Performance Characteristics

Concurrent Operations: All critical paths support concurrent execution
Memory Efficiency: Streaming parsers for large files
Caching: Template compilation and static asset caching
Optimization: Profile-guided optimizations for hot paths

Running Benchmarks

# Run all benchmarks
magex bench

# Run specific component benchmarks
go test -bench=. ./internal/parser/...
go test -bench=. ./internal/badge/...
go test -bench=. ./internal/analytics/...
go test -bench=. ./internal/history/...
go test -bench=. ./internal/analysis/...

# Run with memory profiling
go test -bench=. -benchmem ./...

# Generate benchmark comparison
go test -bench=. -count=5 ./... | tee new.txt
benchstat old.txt new.txt

Real-World Metrics

⚡ CI/CD Integration: Adds < 2 seconds to your workflow
📊 Memory Efficient: Peak usage under 10MB for large repositories
🚀 GitHub Pages: Deploy coverage reports in under 30 seconds
📈 Scalable: Tested with repositories containing 100,000+ lines of code

Performance benchmarks measured on GitHub Actions runners (10-core CPU) with production Go projects.

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.

🤖 Claude Code Sub-Agents & Commands

Sub-Agents Overview

This project leverages a comprehensive team of specialized Claude Code sub-agents to manage development, testing, and deployment workflows. Each agent has specific expertise and can work independently or collaboratively to maintain the go-coverage system.

Available Sub-Agents

Agent	Specialization	Primary Tools	Proactive Triggers
go-test-runner	Test execution, coverage analysis, failure resolution	Bash, Read, Edit, Task	After code changes, before PRs
go-linter	Code formatting, linting, standards enforcement	Bash, Edit, Glob	After any Go file modification
coverage-analyzer	Coverage reports, badges, GitHub Pages deployment	Bash, Write, WebFetch	After successful test runs
github-integration	PR management, status checks, API operations	Bash, WebFetch	PR events, deployments
dependency-manager	Module updates, vulnerability scanning	Bash, Edit, WebFetch	go.mod changes, weekly scans
ci-workflow	GitHub Actions, pipeline optimization	Read, Edit, Bash	Workflow failures, CI updates
code-reviewer	Code quality, security review, best practices	Read, Grep, Glob	After code writing/modification
documentation-manager	README, API docs, changelog maintenance	Read, Edit, WebFetch	API changes, new features
performance-optimizer	Benchmarking, profiling, optimization	Bash, Edit, Grep	Performance issues, benchmarks
security-scanner	Vulnerability detection, compliance checks	Bash, Grep, WebFetch	Security advisories, scans
debugger	Error analysis, test debugging, issue resolution	Read, Edit, Bash	Test failures, errors, panics

Using Sub-Agents

Sub-agents can be invoked in two ways:

Automatic Delegation: Claude Code automatically delegates tasks based on context and the agent's specialization

Explicit Invocation: Request a specific agent by name:

> Use the code-reviewer agent to review my recent changes
> Have the debugger investigate this test failure
> Ask the coverage-analyzer to generate a new report

Agent Coordination

Sub-agents work together cohesively:

go-test-runner → triggers coverage-analyzer after successful tests
code-reviewer → invokes go-linter for style issues
dependency-manager → calls security-scanner for vulnerability checks

Configuration

Sub-agent configurations are stored in .claude/agents/ and can be customized:

Edit agent prompts to adjust behavior
Modify tool access for security constraints
Add project-specific instructions

Benefits

Specialized Expertise: Each agent excels in its domain
Parallel Processing: Multiple agents can work simultaneously
Isolated Contexts: Agents maintain separate contexts to prevent pollution
Consistent Workflows: Standardized approaches across the team
Improved Efficiency: Faster task completion with focused agents

For detailed information about each sub-agent's capabilities and configuration, see the individual agent files in .claude/agents/.

Claude Code Commands

The project includes 20 powerful slash commands that orchestrate our sub-agents for common development tasks. These commands provide quick access to complex workflows:

Quick Examples

/fix              # Automatically fix test failures and linter issues
/test parser.go   # Create comprehensive tests for a file
/coverage         # Analyze and improve test coverage to 90%+
/pr-ready        # Make your code PR-ready with all checks
/review          # Get comprehensive code review
/secure          # Run security vulnerability scan
/health          # Complete project health check

Command Categories

Quality & Testing: /fix, /test, /coverage, /dedupe
Documentation: /doc-update, /doc-review, /explain, /prd
Development: /review, /optimize, /refactor
Maintenance: /deps, /secure, /health, /clean
Workflow: /pr-ready, /debug-ci, /release-prep, /benchmark, /commit

See the complete Claude Code Commands Reference for detailed usage, examples, and best practices.

👥 Maintainers


MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 218 Commits
.claude		.claude
.github		.github
.vscode		.vscode
cmd/go-coverage		cmd/go-coverage
docs		docs
internal		internal
.cursorrules		.cursorrules
.devcontainer.json		.devcontainer.json
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitpod.yml		.gitpod.yml
.golangci.json		.golangci.json
.goreleaser.yml		.goreleaser.yml
.mage.yaml		.mage.yaml
LICENSE		LICENSE
README.md		README.md
codecov.yml		codecov.yml
go.mod		go.mod
go.sum		go.sum

Uh oh!

License

mrz1836/go-coverage

Folders and files

Latest commit

History

Repository files navigation

📊 go-coverage

Project Navigation

⚡ Quickstart

Installation

Development Setup

Choose Your Coverage System

Core Features

🚀 GitHub Pages Setup

Quick Setup

What Gets Deployed

Integration with CI/CD

🎯 Starting a New Project

1. Install the CLI Tool

2. Configure GitHub Pages

3. Add to GitHub Actions

4. First Run

📚 Documentation

Quick Start Guides

Reference Documentation

Developer Resources

Features Overview

🎛️ The Workflow Control Center

🧪 Examples & Tests

CLI Command Examples

Testing the Coverage System

Available Fuzz Tests

Running Fuzz Tests

Fuzz Test Features

Example Output

⚡ Performance

Benchmark Results

Performance Characteristics

Running Benchmarks

Real-World Metrics

🛠️ Code Standards

🤖 AI Usage & Assistant Guidelines

Sub-Agents Overview

Available Sub-Agents

Using Sub-Agents

Agent Coordination

Configuration

Benefits

Claude Code Commands

Quick Examples

Command Categories

👥 Maintainers

🤝 Contributing

How can I help?

📝 License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 26

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

`Project Navigation`

Packages