DEV Community

Cover image for Add a repository health badge to your GitHub README in 10 seconds
Adam
Adam

Posted on

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

#github #showdev #productivity #opensource

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)
Enter fullscreen mode Exit fullscreen mode

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

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

2. Maintenance Status

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

Maintained

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

3. Response Time

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

Response Time

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

4. Contributors

Actual contributor count from GitHub API.

Contributors

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

5. Contributor Friendly

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

Contributor Friendly

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

6. Issues Welcome

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

Issues Welcome

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

7. Documentation Quality

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

Docs

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

8. Issues Resolved

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

Resolved

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

9. Label Count

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

Label Count

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

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

Customize the Style

Add ?style= to change the look:

Flat (default):

?style=flat
Enter fullscreen mode Exit fullscreen mode

Square:

?style=flat-square
Enter fullscreen mode Exit fullscreen mode

Bold (great for headers):

?style=for-the-badge
Enter fullscreen mode Exit fullscreen mode

Custom Colors

Change the value color with ?color=:

https://api.gitscope.dev/api/badges/owner/repo.svg?color=purple
Enter fullscreen mode Exit fullscreen mode

Dark mode with ?labelColor=:

https://api.gitscope.dev/api/badges/owner/repo.svg?labelColor=dark
Enter fullscreen mode Exit fullscreen mode

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...
Enter fullscreen mode Exit fullscreen mode

→ 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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)