Skip to content

Home

Jump to bottom
Ferran Buireu edited this page Oct 17, 2026 · 17 revisions

Track star counts across every repository your token can see, on a schedule, with reports, charts and optional email alerts.

GitHub Star Tracker is a GitHub Action that monitors star counts across all your repositories, generates historical reports with charts and forecasts, and optionally emails you once enough has changed to be worth reading.

What It Does

  • Fetches star counts for your repos via the GitHub API
  • Compares against the previous snapshot to compute deltas
  • Generates a Markdown report, an SVG badge, animated SVG charts and an HTML email digest
  • Commits everything to an isolated data branch, so your main branch is never touched
  • Optionally tracks individual stargazers and produces growth forecasts
  • Sends email notifications once the threshold is reached

Quick Navigation

Page Description
Getting Started Token setup, first workflow, first run
How It Works Execution flow, data pipeline, phase by phase
Architecture DDD(ish) layers, how much DDD and where it stops
Technical Stack Why these tools and these dependencies
Personal Access Token (PAT) Classic & fine-grained token creation
Configuration All available options, file-based config, precedence
API Reference Complete inputs, outputs, and data formats
Examples Real-world workflows and advanced recipes
Star Trend Charts SVG charts, QuickChart URLs, chart types
Email Notifications Built-in SMTP and external action setup
Viewing Reports Data branch, badges, action outputs
Data Management Snapshots, history rotation, generated files
Internationalization (i18n) Multi-language support (en, es, ca, it)
Known Limitations Technical constraints and design trade-offs
Troubleshooting Common issues and solutions
CI/CD For contributors: how this repository checks, releases and publishes itself

Minimal Setup

One step, one secret:

- uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.STAR_TRACKER_TOKEN }}

Note

STAR_TRACKER_TOKEN must be a Personal Access Token with repo or public_repo scope. The default GITHUB_TOKEN is not sufficient: it cannot list repositories outside the repository that triggered the run.

The job still needs permissions: contents: write: with actions/checkout's default persist-credentials: true, git pushes the data branch with the workflow's GITHUB_TOKEN, and falls back to github-token only when checkout persisted nothing.

See Getting Started for the full walkthrough: the complete workflow file, the first run, and what lands on the data branch.

License

AGPL-3.0, made by Ferran Buireu

Clone this wiki locally