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

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:

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

Then audit any repo:

python main.py itxashancode/Pull-Shark-Automation

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

🛠️ 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

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! 👇