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
[![Stargazers over time](docs/star-history.svg)](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.