DEV Community

Cover image for 🏥 gh-repo-health: Check Your GitHub Repo's Health Score in Seconds
Ashan_Dev
Ashan_Dev

Posted on

🏥 gh-repo-health: Check Your GitHub Repo's Health Score in Seconds

#github #opensource #python #devtools

Have you ever opened a GitHub repo and wondered "is this project actually maintained?" — or pushed your own project and asked "does this even look professional?"

I asked myself the same questions. So I built gh-repo-health — a CLI tool that audits any GitHub repository and gives it a health score based on community standards.

🤔 Why I Built This

When I was exploring open source projects to contribute to, I kept manually checking:

  • Does it have a README?
  • Is there a CONTRIBUTING guide?
  • Any issue templates?
  • A LICENSE file?
  • A CODE_OF_CONDUCT?

Doing this for every repo was exhausting. I wanted a single command that tells me everything at once.

So I built gh-repo-health.

⚡ What It Does

gh-repo-health scans any public GitHub repository and checks for key community health files:

File Why It Matters
README.md First impression — does the project explain itself?
LICENSE Legal clarity for contributors and users
CONTRIBUTING.md Guides new contributors on how to help
CODE_OF_CONDUCT.md Sets community standards
SECURITY.md Responsible disclosure for vulnerabilities
Issue Templates Structured bug reports and feature requests
Pull Request Template Consistent PR process

Each check passes or fails, and you get an overall health score at the end.

🚀 Getting Started

Clone the repo and run it against any GitHub repository:

git clone https://github.com/itxashancode/gh-repo-health
cd gh-repo-health
pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

Then audit any repo:

python main.py itxashancode/Pull-Shark-Automation
Enter fullscreen mode Exit fullscreen mode

You'll get output like:

✅ README.md          found
✅ LICENSE            found
❌ CONTRIBUTING.md    missing
❌ CODE_OF_CONDUCT    missing
✅ Issue Templates    found
❌ SECURITY.md        missing
❌ PR Template        missing

Health Score: 43% — Needs Improvement
Enter fullscreen mode Exit fullscreen mode

🛠️ How It Works

The tool uses the GitHub REST API to check for the existence of community health files. No cloning required — it's all API calls.

import requests

def check_file(owner, repo, filepath):
    url = f"https://api.github.com/repos/{owner}/{repo}/contents/{filepath}"
    response = requests.get(url)
    return response.status_code == 200
Enter fullscreen mode Exit fullscreen mode

It checks common file locations — root, .github/, and docs/ — so it doesn't miss files tucked in subdirectories.

💡 What I Learned Building This

This was one of my early Python projects, and it taught me a lot:

  1. GitHub's API is incredibly powerful — you can inspect almost anything about a repo without cloning it
  2. Community health files genuinely matter — repos with them get more contributions
  3. CLI tools are satisfying to build — instant feedback, no UI needed
  4. Error handling is critical — private repos, rate limits, and missing tokens all need to be handled gracefully

🔮 What's Next

I'm planning to add:

  • [ ] Badge generation — embed a health score badge in your README
  • [ ] Batch scanning — audit all repos in an organization at once
  • [ ] GitHub Actions integration — fail CI if health score drops below a threshold
  • [ ] JSON output — for piping results into other tools

🌟 Try It on Your Own Repo

Run gh-repo-health against your own projects. You might be surprised what's missing!

👉 GitHub: itxashancode/gh-repo-health

If you find it useful, drop a ⭐ on the repo — it genuinely motivates me to keep building.

I'm Ashan, an APTECH student from Karachi building GitHub automation tools and learning in public. If you have ideas for features, drop them in the comments below — I read every one! 👇

Top comments (1)

Collapse
 
ljhao profile image
LocalAI Agent •

If you build it like an agent skill, I believe more people will use it.😀