Ossama Hashim

Posted on Apr 6

I built a free GitHub Action that scores your repo health — and auto-updates your README

#opensource #github #productivity #devops

Ever looked at a repo and thought: "Is this actually well-maintained, or does it just look like it is?"

I had that thought one too many times — so I built DevLens.

What is DevLens?

DevLens is a GitHub Action that gives your repository a health score from 0 to 100, auto-injects a live badge into your README, and sends a weekly analytics digest to Discord.

It's 100% free. Runs entirely inside GitHub Actions. Zero vendor lock-in. Forever.

vs. Code Climate ($37/dev) · LinearB ($49/dev) · GitClear ($15/dev)
DevLens costs $0.

The 7 Health Dimensions

DevLens scores your repo across 7 weighted dimensions:

Dimension	Weight	What it checks
📝 README Quality	20%	Length, sections, badges, code examples, keywords
🔥 Commit Activity	20%	Push frequency over last 90 days
🌿 Repo Freshness	15%	Days since last push
📚 Documentation	15%	LICENSE, CONTRIBUTING, CHANGELOG, CODE_OF_CONDUCT, SECURITY, docs/
⚙️ CI/CD Setup	15%	GitHub Actions workflows present
🎯 Issue Response	10%	Closed vs open issue ratio
⭐ Community Signal	5%	Stars, forks, watchers

The result? A single number that tells you — and your contributors — exactly where the repo stands.

What it looks like in your README

After each push, DevLens auto-commits a live badge between two markers in your README:

<!-- DEVLENS:START -->
## Repository Health

This repository has a health score of 91.

**Repo Status:**
- **readme**: 100
- **activity**: 75
- **freshness**: 100
- **docs**: 96
- **ci**: 100
- **issues**: 100
- **community**: 0
<!-- DEVLENS:END -->

No manual updates. Every push keeps it fresh.

Setup in 30 seconds

Step 1 — Add markers to your README.md:

<!-- DEVLENS:START -->
<!-- DEVLENS:END -->

Step 2 — Create .github/workflows/devlens.yml:

name: DevLens Health Check

on:
  push:
    branches: [main, master]
  schedule:
    - cron: '0 8 * * 1'  # Weekly Monday digest

permissions:
  contents: write

jobs:
  devlens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SamoTech/devlens@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          groq_api_key: ${{ secrets.GROQ_API_KEY }}       # optional — free
          notify_discord: ${{ secrets.DISCORD_WEBHOOK }}  # optional

That's it. On the next push, DevLens scores your repo and updates your README automatically.

AI-Powered Insights (Free)

Add a free Groq API key and DevLens uses Llama 3 to write a human-readable health summary directly into your README — not just numbers, but actual sentences explaining what's strong and what needs attention.

No paid AI tier. No OpenAI credits. Just a free Groq key.

Weekly Discord Digest

Set a DISCORD_WEBHOOK secret and every Monday at 8am UTC your team gets a rich embed with all 7 dimension scores, the overall health score, and a direct link to the repo.

Perfect for teams who want passive repo hygiene awareness without checking dashboards.

How to score 100/100

Here's exactly what DevLens looks for:

✅ LICENSE file present
✅ CONTRIBUTING.md present
✅ CHANGELOG.md present
✅ CODE_OF_CONDUCT.md present
✅ SECURITY.md present
✅ docs/ folder present
✅ README with install, usage, features, examples, roadmap sections
✅ Code blocks and images in README
✅ 3+ GitHub Actions workflows
✅ 30+ commits in the last 90 days
✅ All issues closed (or healthy ratio)

Roadmap

[x] 7-dimension health score engine
[x] Auto README badge injection
[x] Weekly Discord digest
[x] AI README insights (Groq/Llama 3)
[ ] Web dashboard (Next.js)
[ ] Email digest (Resend free tier)
[ ] PR quality scoring
[ ] Historical trend charts
[ ] Multi-repo portfolio view
[ ] Slack integration

It's free. Forever.

No trials. No paywalls. No "Pro" tier. DevLens is — and always will be — completely free.

If it saves you time or helps your team ship better code, a ⭐ on GitHub means the world:

👉 github.com/SamoTech/devlens

And if you want to say thanks beyond a star — sponsorships are open. No pressure. Just love. 💛

Built with GitHub Actions + Groq + ☕ by @SamoTech

DEV Community