I wanted a simple way to showcase the top contributors across all my GitHub repositories directly on my GitHub profile README.
Something like contrib.rocks, but across all repositories..
Surprisingly, I couldn't really find a clean solution for it.
Most existing tools were either:
- repo-specific
- difficult to self-host
- dependent on live GitHub API scraping
- heavily rate limited
- or just abandoned
So I built one.
🏆 Top Contributors API
Website:
https://top-contributors-api.vercel.app/
How it looks like:
🤔 Why I Built It
Originally, I just wanted this for my own GitHub profile.
Something simple:
- aggregate contributors across all repos
- render avatars nicely
- auto-update
- easy to embed
- no maintenance headaches
I assumed someone had already built it.
Apparently not.
Or at least not in the way I wanted.
So this became one of those:
“Fine, I'll build it myself.”
projects.
⚠️ The Real Problem Wasn't the Image
Rendering the image itself was easy.
The painful part was:
- iterating through repositories
- merging contributor data
- pagination
- GitHub API rate limits
- serverless execution limits
- caching
- keeping response times fast
At first I tried doing everything live inside a Vercel API route.
Bad idea.
If a profile has enough repositories, the function can easily hit execution limits. And repeatedly querying GitHub on every request is basically asking to get throttled.
So I redesigned the architecture.
🧠 How It Works
1. GitHub Actions Handles Aggregation
A scheduled GitHub Actions workflow:
- scans public repositories
- aggregates contributor stats
- generates a lightweight
contributors.json - commits it back into the repository
It uses GitHub’s built-in GITHUB_TOKEN, so setup stays extremely simple.
2. Vercel Only Renders the Image
The API route:
- reads the JSON file
- renders contributor avatars using
canvas - returns a PNG image
Which means:
- fast response times
- edge caching
- minimal GitHub API usage
- no live scraping during requests
Also, using PNGs avoids GitHub README SVG sanitization weirdness, which was another unexpected rabbit hole.
🔥 Two Versions
Main Version (Recommended)
Repository:
https://github.com/vishnunandan555/top-contributors-api
This version is meant for:
- self-hosting
- private usage
- maximum reliability
- zero public API dependency
Setup
- Fork the repository
- Enable GitHub Actions
- Run the
Aggregate Top Contributorsworkflow once - Deploy to Vercel
- Use your Vercel Link
No environment variables required.
This avoids public rate limits entirely.
OTG Edition
This version provides a public API.
(you can find it in the website)
You just:
- place your GitHub username in the URL
- paste it into your README
- done
Perfect for quick setup.
Because it's a shared public instance, it can get rate limited under heavy usage, although in normal usage it usually works fine.
📌 Future Plans
Currently the output is a static image.
One thing I really want to add is interactive contributor avatars, so clicking a contributor directly opens their GitHub profile.
📎 About Contribution Calculation
Currently, contributors are ranked using aggregated commit counts across repositories via GitHub’s contributors API.
Is commit count a perfect measure of contribution? Not really.
It ignores things like:
- code reviews
- issue triage
- mentoring
- discussions
- documentation/design work
But commits are the most practical metric GitHub exposes that is fast, scalable, and reliable for an automated README widget.
In the future, I’d like to experiment with a smarter scoring system that can better represent contribution quality instead of just raw commit volume.
Top comments (0)