DEV Community: Adam

Add a repository health badge to your GitHub README in 10 seconds

Adam — Tue, 30 Dec 2025 17:09:34 +0000

You know those badges at the top of every GitHub README? They tell you if the build works and what license it uses. Cool.

But they don't tell you what actually matters:

Is this repo actively maintained?
How fast do maintainers respond to issues?
Is there a massive backlog of ignored issues?
Should I actually depend on this project?

So I built badges that answer those questions.

Quick Start

Add this to your README (replace owner/repo with your repository):

[![Repo Health](https://api.gitscope.dev/api/badges/owner/repo.svg)](https://gitscope.dev)

That's it. No signup. No API key. No configuration.

-> See live examples on any repo

-> Read the docs

All Available Badges

Visit gitscope.dev/badges for the full list.

1. Repo Health Score

Overall repository health from 0-100%. Combines activity, maintenance, community engagement, and issue management.

[![Repo Health](https://api.gitscope.dev/api/badges/owner/repo/health.svg)](https://gitscope.dev)

2. Maintenance Status

Shows: very active | active | maintained | stale based on recent commit and issue activity.

[![Maintained](https://api.gitscope.dev/api/badges/owner/repo/maintained.svg)](https://gitscope.dev)

3. Response Time

Activity-based indicator showing how recently the repo was updated.

[![Response Time](https://api.gitscope.dev/api/badges/owner/repo/response-time.svg)](https://gitscope.dev)

4. Contributors

Actual contributor count from GitHub API.

[![Contributors](https://api.gitscope.dev/api/badges/owner/repo/contributors.svg)](https://gitscope.dev)

5. Contributor Friendly

Indicates if the repo welcomes new contributors based on good first issues, contributing guides, and response patterns.

[![Contributor Friendly](https://api.gitscope.dev/api/badges/owner/repo/contributor-friendly.svg)](https://gitscope.dev)

6. Issues Welcome

Shows if the project actively accepts and responds to issue reports.

[![Issues Welcome](https://api.gitscope.dev/api/badges/owner/repo/issues.svg)](https://gitscope.dev)

7. Documentation Quality

Based on README completeness, wiki presence, and linked documentation.

[![Documentation](https://api.gitscope.dev/api/badges/owner/repo/docs.svg)](https://gitscope.dev)

8. Issues Resolved

Percentage of issues that have been closed. Calculated as closed / (open + closed).

[![Issues Resolved](https://api.gitscope.dev/api/badges/owner/repo/resolved.svg)](https://gitscope.dev)

9. Label Count

Count of open issues with a specific label. Great for showing bug counts.

[![Bug Count](https://api.gitscope.dev/api/badges/owner/repo/label/bug.svg)](https://gitscope.dev)

Replace bug with any label name (case-sensitive).

Customize the Style

Add ?style= to change the look:

Flat (default):

?style=flat

Square:

?style=flat-square

Bold (great for headers):

?style=for-the-badge

Custom Colors

Change the value color with ?color=:

https://api.gitscope.dev/api/badges/owner/repo.svg?color=purple

Dark mode with ?labelColor=:

https://api.gitscope.dev/api/badges/owner/repo.svg?labelColor=dark

Available colors: brightgreen green yellow orange red blue cyan purple pink teal indigo gray

Or use hex codes: ?color=ff69b4

Full README Example

Here's how to add multiple badges:

# My Awesome Project

[![Build](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/owner/repo/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Repo Health](https://api.gitscope.dev/api/badges/owner/repo/health.svg)](https://gitscope.dev)
[![Maintained](https://api.gitscope.dev/api/badges/owner/repo/maintained.svg)](https://gitscope.dev)
[![Contributors](https://api.gitscope.dev/api/badges/owner/repo/contributors.svg)](https://gitscope.dev)

A brief description of your awesome project...

→ Generate badges for your repo

Why This Matters

For users/contributors:

Know if a project is actually maintained before depending on it
See if maintainers are responsive before opening issues
Find contributor-friendly projects

For maintainers:

Finally get credit for your maintenance work
Signal that your project is healthy and active
Attract contributors who value responsive maintainers

How Scores Are Calculated

Factor	Weight	What it measures
Activity	20 pts	Days since last commit
Issue Management	15 pts	Open issues relative to popularity
Community	10 pts	Description, license, homepage
Engagement	5 pts	Stars and forks

Badges are served from Cloudflare's edge network with 15-minute caching. Response times are typically under 100ms worldwide.

FAQ

Do I need to sign up?
Nope. Badges work instantly with any public GitHub repository.

How often do badges update?
Data is cached for 15 minutes. Health metrics recalculate hourly.

Will this slow down my README?
No. Edge-cached, globally distributed, sub-100ms response times.

Try It Now

→ Generate badges for your repo

Or construct the URL yourself:

https://api.gitscope.dev/api/badges/YOUR-ORG/YOUR-REPO.svg

Drop Your Repo Below 👇

Comment with your repository and I'll share your health score!

Building GitScope to help OSS maintainers not burn out. Badges are free forever. Full docs here.

I analyzed 50 GitHub repos and found why maintainers are mass-quitting

Adam — Tue, 30 Dec 2025 14:30:38 +0000

Last month, three prominent OSS maintainers stepped down citing burnout. The month before, two more. There's a pattern here, and it's not about code.

I spent a weekend analyzing 50 active GitHub repositories (100-5000 stars) to understand what's actually draining maintainers. The results surprised me.

TL;DR: It's not the coding. It's the endless, repetitive issue triage that nobody talks about.

The Numbers That Should Worry Us

Across 50 repositories, I found:

Metric	Average	Worst Case
Open issues	127	847
Issues with no response (>7 days)	34%	72%
Likely duplicates	18%	41%
Issues missing category labels	61%	94%
Average first response time	6.3 days	89 days

The pattern was clear: maintainers aren't drowning in code problems. They're drowning in triage.

The Hidden Time Sink

I talked to 12 maintainers during this research. Here's what they said:

"I spend more time categorizing issues than actually fixing bugs." — Maintainer of a 2K star project

"Every morning I wake up to 10 new issues. Maybe 2 are actually actionable. But I have to read all 10 to find out." — Core contributor to a popular framework

"The duplicates are killing me. Users don't search before posting." — Solo maintainer of a widely-used library

One maintainer tracked their time for a month. The breakdown:

Issue triage (reading, categorizing, responding): 47%
Actual development: 31%
PR review: 15%
Documentation: 7%

Almost half their "maintenance" time was just... sorting through issues.

The Stale-Bot Problem

Many repos have turned to stale-bot as a solution. Here's how it works: if an issue hasn't had activity in X days, the bot comments "this issue is stale" and eventually closes it.

Sounds reasonable. But here's what's actually happening:

From the "fuck-you-stale-bot" repo (yes, this exists):

"Sending a bot to tell people their contribution has been promoted from ignored to abandoned-without-a-word? That sucks."

From a GitHub community discussion:

"I personally hate the stale bot... it's awful software for a lousy purpose. Makes a mess of sorting by bubbling up stale items."

From the OpenSCAD repo discussion:

"GitHub stale bots are widely criticized... they create poor contributor experience, punish maintainer inactivity, create busywork, hide real project health."

Stale-bot doesn't solve the triage problem. It just hides it by mass-closing issues — including valid ones.

What Actually Eats Maintainer Time

Breaking down the triage work:

1. Reading and Understanding (35% of triage time)

Every issue requires reading and mental context-switching. Even a "quick look" takes 2-3 minutes. Multiply by 10 issues/day = 30 minutes just reading.

2. Categorization (25% of triage time)

Is this a bug? Feature request? Question that belongs on Stack Overflow? Documentation issue? Security concern?

Most repos have label systems, but applying them manually is tedious.

3. Duplicate Detection (20% of triage time)

"Didn't someone report this last month?"

Searching through hundreds of issues (open AND closed) to find potential duplicates is soul-crushing work.

4. Response Crafting (20% of triage time)

Writing the same responses over and over:

"Can you provide more details?"
"What version are you using?"
"This looks like a duplicate of #234"
"This is expected behavior, see docs"

The Math of Maintainer Burnout

Let's do the math for a moderately popular project:

10 new issues per week (pretty typical for 1-2K stars)
15 minutes average triage time per issue
= 2.5 hours/week just on initial triage

That's 130 hours per year — over 3 full work weeks — just sorting through incoming issues. Not fixing them. Just sorting.

For larger projects (50+ issues/week), this becomes a full-time job that nobody signed up for.

What's Actually Working

I looked for repos that seemed to have this under control. Common patterns:

1. Issue Templates That Actually Filter

The best repos have templates that:

Force categorization upfront (bug/feature/question)
Require reproduction steps for bugs
Auto-close issues that don't follow the template

Example from a well-maintained repo:

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
body:
  - type: checkboxes
    attributes:
      label: Prerequisites
      options:
        - label: I searched existing issues and this is not a duplicate
          required: true

2. Triage Teams (If You're Lucky)

Some larger projects have dedicated triage teams. But this requires either:

Corporate backing
A large contributor community
Someone willing to do unpaid triage work

Most projects don't have this luxury.

3. Automation Beyond Stale-Bot

A few repos are using smarter automation:

Auto-labeling based on keywords
Duplicate detection bots
Response template bots

The tech exists. It's just fragmented and requires setup.

The Opportunity

Here's what I think is missing: intelligent triage that actually understands context.

Not "close after 30 days of inactivity."

But:

"This looks like a bug in the auth module, similar to issues #234 and #456"
"This is a feature request that's been asked 3 times before"
"This needs more information — here's a response template"

The technology for this exists (LLMs are pretty good at categorization). The tooling doesn't — at least not in a way that's easy for maintainers to use.

Quick Win: Show Off Your Health Score

While you're improving your triage process, let the world know
with a health badge:

Just paste in your README (no signup needed):

[![Repo Health](https://api.gitscope.dev/api/badges/ORG-NAME/REPO-NAME.svg)](https://gitscope.dev)

See all badge types →

What I'm Building

Full disclosure: I started building a tool to solve this for myself, and it's turned into something others might find useful.

GitScope analyzes your GitHub issues and:

Auto-categorizes by type (bug/feature/docs/question)
Catches duplicates before they pile up
Suggests response templates
Surfaces issues that actually need human attention

It's free for public repos. I'm not trying to sell you anything — I genuinely just want feedback from maintainers who've dealt with this problem.

Try it on your repo →

The Bigger Picture

Maintainer burnout isn't a personal failing. It's a systemic problem.

We've built incredible tooling for writing code, reviewing code, deploying code, and monitoring code. But we've completely neglected the human side of maintenance — the community management, the triage, the endless context-switching.

Every maintainer who quits takes institutional knowledge with them. Every abandoned project creates downstream pain for thousands of developers.

We can build better tools for this. We should.

Discussion

I'd love to hear from maintainers:

How much of your time goes to triage vs. actual development?
What tools/processes have actually helped?
What would your ideal triage tool look like?

Drop a comment — I'm genuinely trying to understand this problem better.

If you found this useful, I write about OSS sustainability and developer tools. Follow for more.