CLI tool that scans a Git repository and produces a health score (0-100) based on 20+ signals.
No single CLI tool gives a holistic repo health score with actionable recommendations. repo-health fills that gap — run it locally, in CI, or as a GitHub Action.
Install
pip install repo-health
Usage
# Scan current directory
repo-health
# Scan specific path
repo-health scan /path/to/repo
# JSON output for CI
repo-health scan --format json --output report.json
# Markdown report
repo-health scan --format markdown --output HEALTH.md
# Generate badge SVG
repo-health badge --output health-badge.svg
# Fail CI if below threshold
repo-health scan --min-score 70
# CI mode (JSON output, non-zero exit on failure)
repo-health scan --ci --min-score 60
Output Example
╭─────────────────────────────────────────────╮
│ 🏥 Repository Health Report │
│ my-project · Score: 78/100 B+ │
╰─────────────────────────────────────────────╯
┌────────────┬───────┬────────────────────────────────┐
│ Category │ Score │ Details │
├────────────┼───────┼────────────────────────────────┤
│ CI/CD │ 90 │ ✅ CI config, ✅ tests in CI │
│ Testing │ 70 │ ✅ Tests exist, ⚠️ No coverage │
│ Docs │ 85 │ ✅ README, ✅ LICENSE, ❌ CHANGELOG│
│ Security │ 60 │ ✅ .gitignore, ❌ SECURITY.md │
│ Deps │ 75 │ ✅ Lock file, ⚠️ 3 outdated │
│ Community │ 80 │ ✅ Issue template, ❌ COC │
│ Release │ 70 │ ✅ Tags, ❌ No release notes │
│ Git │ 90 │ ✅ Clean history │
└────────────┴───────┴────────────────────────────────┘
💡 Top Recommendations:
1. Add CHANGELOG.md to track version history
2. Create SECURITY.md with vulnerability reporting process
3. Add coverage reporting to CI pipeline
Health Signals (20+)
| Category | Signals |
|---|---|
| CI/CD | CI config exists, tests run in CI, build step, deploy step |
| Testing | Test files exist, coverage config, coverage threshold |
| Documentation | README quality (sections, badges), CONTRIBUTING, CHANGELOG, LICENSE |
| Security | .gitignore completeness, no secrets in repo, SECURITY.md, dependency audit |
| Dependencies | Manifest exists, lock file, version pinning, audit tool |
| Community | Issue templates, PR templates, CODE_OF_CONDUCT, CONTRIBUTING |
| Release | Tagged releases, semantic versioning, release notes |
| Git Hygiene | Git repo, commit message quality, default branch |
Configuration
Create .repo-health.toml in your repo root:
[weights]
ci = 15
testing = 20
documentation = 10
security = 15
dependencies = 10
community = 10
release = 10
git_hygiene = 10
[thresholds]
min_score = 70
[ignore]
scanners = []
files = ["vendor/"]
Or add to pyproject.toml:
[tool.repo-health.weights]
testing = 20
[tool.repo-health.thresholds]
min_score = 70
GitHub Action
- uses: repo-health/repo-health@v1
with:
min-score: 60
format: json
Contributing
- Fork the repository
- Create a feature branch
- Run tests:
pytest --cov - Submit a pull request
License
Metadata
Release files for repo-health 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| repo_health-1.0.0.tar.gz | 1.5 MB | With provenance | Details for repo_health-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| repo_health-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for repo_health-1.0.0-py3-none-any.whl |
Total release size: 1.5 MB
Release files / repo_health-1.0.0.tar.gz
| Download URL | repo_health-1.0.0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
22e3b7317f67e1037ba78284a115706733a0506b8943f1818bf544d3ed8f0d78
|
|
BLAKE2b-256 checksum How to use checksums |
774f9779b46fd0fdbafef5b9a3906ed5cc1440f8f0d66297581b2a76c8c42e4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency logRelease files / repo_health-1.0.0-py3-none-any.whl
| Download URL | repo_health-1.0.0-py3-none-any.whl |
|---|---|
| Size | 23.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5bf28acd6040bc3b3839d545a02d153333b872c7a74ab4f6cd9acc03a97af0ab
|
|
BLAKE2b-256 checksum How to use checksums |
f463e3eadae86b7efe8be697d5b8b14329011dfa98725787612059a4f6ad7717
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency logSecurity for repo-health 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for repo_health-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.