| name | star-history-chart |
| description | Add a self-hosted "Stargazers over time" chart to any GitHub repo's README. GitHub now restricts the stargazers endpoint to a repo's own admins/collaborators, so third-party live services (star-history free tier, starchart.cc) return "Requires authentication" for everyone. This generates a static, theme-aware SVG in-repo and auto-refreshes it weekly with a GitHub Action using the repo's own GITHUB_TOKEN. Use when the star chart in a README is broken, shows "Requires authentication", or you want a star history that never breaks. |
Star History Chart (self-hosted, never breaks)
Add a "Stargazers over time" chart that renders from a static SVG committed to
the repo and refreshes itself weekly — no external chart service, no broken
images.
Why this exists
GitHub now restricts the /stargazers endpoint to a repository's own admins and
collaborators. Unauthenticated requests return {"message":"Requires authentication"}, which breaks every third-party live-chart service
(star-history.com free tier, starchart.cc, etc.) for all repos. The only
reliable fix is to generate the chart yourself with an authenticated token and
commit a static image. Inside GitHub Actions, the repo's own GITHUB_TOKEN can
read its own stargazers, so the whole thing runs with zero secrets to configure.
What this skill sets up
scripts/generate_star_history.py — fetches stargazers (authenticated),
renders a clean, light/dark-adaptive SVG..github/workflows/star-history.yml — weekly cron + manual trigger that
regenerates and commits docs/star-history.svg.- A README section pointing at the local SVG.
Workflow
Step 1: Copy the script and workflow into the repo
mkdir -p scripts .github/workflows docs
cp skills/git/star-history-chart/scripts/generate_star_history.py scripts/generate_star_history.py
cp skills/git/star-history-chart/assets/star-history.yml .github/workflows/star-history.yml
The script needs the requests package: pip install requests.
It resolves the repo from STAR_HISTORY_REPO, then GITHUB_REPOSITORY
(set automatically in Actions), then the origin git remote — so no edits
are required for it to work in a different repo.
Step 2: Generate the SVG once, locally
Use a token that can read the repo's stargazers (as owner/collaborator). The
GitHub CLI provides one:
GITHUB_TOKEN=$(gh auth token) python scripts/generate_star_history.py
This writes docs/star-history.svg. For a repo with many thousands of stars the
first run paginates the whole stargazer list and can take a couple of minutes.
Verify it rendered (optional, macOS): qlmanage -t -s 800 -o . docs/star-history.svg
Step 3: Add it to the README
Add or replace the star chart section. Point the image at the local SVG.
Set the link target to wherever you want clicks to go (the repo, a docs page, or
your own site):
## Stargazers over time
[](https://github.com/OWNER/REPO/stargazers)
If replacing a broken star-history.com / starchart.cc embed, swap only the
image URL to docs/star-history.svg and keep or update the link target.
Step 4: Commit
git add scripts/generate_star_history.py .github/workflows/star-history.yml docs/star-history.svg README.md
git commit -m "feat(readme): self-hosted stargazers chart with weekly auto-refresh"
git push
Step 5: (Optional) Trigger the auto-refresh now
The workflow runs every Monday at 04:00 UTC. To refresh immediately without
waiting: GitHub → Actions → "Update Star History" → Run workflow.
Customization
- Output path — set
STAR_HISTORY_OUTPUT (default docs/star-history.svg).
- Different repo — set
STAR_HISTORY_REPO=owner/name.
- Colors / size — edit the
.line, .area, .dot CSS and WIDTH/HEIGHT
constants near the top of generate_star_history.py. The chart is
theme-aware via a prefers-color-scheme: dark block, so it looks right in
both GitHub light and dark modes.
- Refresh cadence — edit the
cron expression in the workflow.
Notes
- No secrets to add: the workflow uses the automatic
GITHUB_TOKEN.
- Private repos work too, as long as the token can read the repo.
- The script uses only
requests plus the Python standard library.
