https://github.com/fbuireu/github-star-tracker
⭐ GitHub Action to automatically track star count changes across repositories with visual charts, email notifications, and historical reports
https://github.com/fbuireu/github-star-tracker
analytics automation badges charts ci-cd devops github github-action github-actions github-stars metrics monitoring notifications reporting repository star-history star-tracker statistics tracker typescript
Last synced: 1 day ago
JSON representation
⭐ GitHub Action to automatically track star count changes across repositories with visual charts, email notifications, and historical reports
- Host: GitHub
- URL: https://github.com/fbuireu/github-star-tracker
- Owner: fbuireu
- License: agpl-3.0
- Created: 2026-02-08T08:57:43.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-06-21T06:22:45.000Z (8 days ago)
- Last Synced: 2026-06-22T10:37:02.586Z (6 days ago)
- Topics: analytics, automation, badges, charts, ci-cd, devops, github, github-action, github-actions, github-stars, metrics, monitoring, notifications, reporting, repository, star-history, star-tracker, statistics, tracker, typescript
- Language: TypeScript
- Homepage: https://github.com/fbuireu/github-star-tracker
- Size: 8.48 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# :star: GitHub Star Tracker
**A GitHub Action that tracks star counts across all your repositories on a schedule, generates visual reports with charts and badges, and sends notifications when changes are detected.**
[](https://github.com/fbuireu/github-star-tracker/actions/workflows/ci.yml)
[](https://codecov.io/gh/fbuireu/github-star-tracker)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://www.producthunt.com/products/github-star-tracker)
**[Documentation](../../wiki)** · **[Getting Started](../../wiki/Getting-Started)** · **[Configuration](../../wiki/Configuration)** · **[Examples](../../wiki/Examples)** · **[Troubleshooting](../../wiki/Troubleshooting)**
---
## Table of Contents
- [What You Get](#what-you-get)
- [Features](#features)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [How It Works](#how-it-works)
- [Embedding in Your README](#embedding-in-your-readme)
- [Documentation](#documentation)
- [Support & Contributing](#support--contributing)
- [Use of AI](#use-of-ai)
---
## What You Get
Every run, Star Tracker commits these artifacts to a dedicated data branch:
- **Animated SVG charts:** star history, per-repo trends, top repos comparison, and growth forecasts - with automatic dark/light mode support:
- **Shields.io-style badge:** embeddable star count that updates automatically:
- **Markdown & HTML reports:** summary tables, delta indicators, new/removed repos, stargazer details, and forecast tables.
- **CSV & JSON data:** machine-readable exports for dashboards, spreadsheets, or downstream pipelines.
---
## Features
- :chart_with_upwards_trend: **Animated SVG charts:** Star history, per-repo trends, comparisons, and growth forecasts
- :crescent_moon: **Dark/light mode:** SVG charts auto-adapt to the viewer's color scheme via `prefers-color-scheme`
- :camera: **Historical snapshots:** Configurable retention (default: 52 runs) with JSON persistence
- :mag: **Smart filtering:** By visibility, ownership, min stars, regex exclusions, archived, forks
- :busts_in_silhouette: **Stargazer tracking:** See who starred your repos with avatars and dates
- :mailbox_with_mail: **Email notifications:** Built-in SMTP with fixed or adaptive thresholds
- :office: **GitHub Enterprise:** GHES support, auto-detected or explicit API URL
- :globe_with_meridians: **Multi-language:** English, Spanish, Catalan, Italian
- :bar_chart: **CSV export:** Machine-readable output for data pipelines
- :jigsaw: **Action outputs:** `total-stars`, `new-stars`, `new-stars`, `lost-stars`, `new-stargazers` (and much more) for workflow chaining
- :shield: **Zero runtime deps:** Bundled TypeScript action, 95%+ test coverage, 490+ tests
---
## Quick Start
### 1. Create a Personal Access Token
1. Go to **[GitHub Settings > Tokens](https://github.com/settings/tokens)**
2. Generate a **classic token** with `repo` or `public_repo` scope
3. Add it as a **repository secret** named `STAR_TRACKER_TOKEN`
> [!NOTE]
> The default `GITHUB_TOKEN` is not sufficient. See the **[PAT guide](<../../wiki/Personal-Access-Token-(PAT)>)** for details.
### 2. Add the Workflow
Create `.github/workflows/star-tracker.yml`:
```yaml
name: Track Stars
on:
schedule:
- cron: '0 0 * * *' # Daily at midnight
workflow_dispatch:
permissions:
contents: write
jobs:
track:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
- uses: fbuireu/github-star-tracker@v1
with:
github-token: ${{ secrets.STAR_TRACKER_TOKEN }}
```
### 3. Run and View
- **Manual run:** Actions > Track Stars > Run workflow
- **View report:** Check the `star-tracker-data` branch in your repository
---
## Configuration
Set options directly in the workflow or via a YAML config file. See the **[Configuration guide](../../wiki/Configuration)** for full details.
```yaml
- uses: fbuireu/github-star-tracker@v1
with:
github-token: ${{ secrets.STAR_TRACKER_TOKEN }}
visibility: 'public' # public | private | all | owned
locale: 'es' # en | es | ca | it
include-charts: true
track-stargazers: true
min-stars: '5'
exclude-repos: 'test-repo,/^demo-.*/'
notification-threshold: '0' # 0 | N | auto
```
All Inputs
| Input | Default | Description |
| ------------------------ | --------------------- | ------------------------------------------------------------- |
| `github-token` | - | **Required.** PAT with `repo` or `public_repo` scope |
| `github-api-url` | - | GitHub API base URL (for GHES). Auto-detected on GHES runners |
| `config-path` | `star-tracker.yml` | Path to YAML config file |
| `visibility` | `all` | `public`, `private`, `all`, or `owned` |
| `locale` | `en` | `en`, `es`, `ca`, or `it` |
| `include-charts` | `true` | Generate star trend charts |
| `data-branch` | `star-tracker-data` | Branch for tracking data |
| `max-history` | `52` | Max snapshots to keep |
| `top-repos` | `10` | Top repos in charts/forecasts |
| `chart-line-color` | `#dfb317` | Hex color of primary chart line/fill/points (not comparison) |
| `chart-line-width` | `2.5` | Stroke width (px, >0) of data lines in all charts |
| `chart-max-points` | `30` | Recent points to plot; `0` plots the full history |
| `chart-y-axis-side` | `left` | Y-axis labels side: `left` or `right` |
| `chart-smoothing` | `true` | Smooth curve (`true`) or straight segments to show spikes; applies to email charts too |
| `chart-show-points` | `true` | Draw a marker on each data point (`true`) or hide them for a cleaner dense line (`false`) |
| `chart-animation` | `true` | Animate SVG charts (`true`) or render them static (`false`) for email/static contexts |
| `chart-milestones` | `true` | Show milestone reference lines on the main star-history chart (`true`) or hide them (`false`) |
| `chart-begin-at-zero` | `false` | Start the Y-axis at zero (`true`) or zoom into the data range (`false`) |
| `chart-theme` | `auto` | Color theme: `auto` (follows `prefers-color-scheme`), `light` or `dark` |
| `chart-custom-milestones` | _(empty)_ | Comma-separated star counts for the milestone reference lines, replacing the built-in defaults (e.g. `250, 750, 2500`). Requires `chart-milestones` |
| `chart-range` | `all` | Time window plotted: `30d`, `90d`, `1y` or `all` |
| `chart-trend-line` | `false` | Overlay a dashed moving-average trend line on the main chart |
| `velocity-metrics` | `false` | Add a growth-velocity section (stars/day, % growth, days to next milestone) to the report |
| `track-stargazers` | `false` | Track individual stargazers |
| `smart-sampling` | `false` | Sample stargazer pages for high-star repos (avoids rate limits) |
| `smart-sampling-threshold` | `1500` | Star count above which a repo is sampled |
| `smart-sampling-pages` | `30` | Max evenly-spaced stargazer pages per sampled repo |
| `include-archived` | `false` | Include archived repos |
| `include-forks` | `false` | Include forked repos |
| `exclude-repos` | - | Names or regex to exclude |
| `only-repos` | - | Only track these repos |
| `only-orgs` | - | Only track repos under these orgs/owners (name or regex) |
| `exclude-orgs` | - | Orgs/owners to exclude (name or regex) |
| `min-stars` | `0` | Min stars to track |
| `smtp-host` | - | SMTP hostname (enables email) |
| `smtp-port` | `587` | SMTP port |
| `smtp-username` | - | SMTP username |
| `smtp-password` | - | SMTP password |
| `email-to` | - | Recipient address |
| `email-from` | `GitHub Star Tracker` | Sender name |
| `send-on-no-changes` | `false` | Email even with no changes |
| `notification-threshold` | `0` | `0` (every run), N (threshold), or `auto` (adaptive) |
In the YAML config file, option keys may be written with either dashes or underscores - `include-charts` and `include_charts` are both accepted - so you can copy option names straight from this table without rewriting the separators.
> [!TIP]
> `chart-line-color` accepts hex with or without a leading `#`. Because a bare `#` starts a comment in YAML, either quote the value (`chart-line-color: '#6b63ff'`) or drop the `#` (`chart-line-color: 6b63ff`).
Outputs
| Output | Description |
| ------------------ | ----------------------------------------------------------------- |
| `total-stars` | Total star count |
| `stars-changed` | `true` / `false` |
| `new-stars` | Stars gained |
| `lost-stars` | Stars lost |
| `should-notify` | Threshold reached: `true` / `false` |
| `new-stargazers` | New stargazers count |
| `report` | Full Markdown report |
| `report-html` | HTML report (for email) |
| `report-html-path` | File path to the HTML report (for large reports / custom mailers) |
| `report-csv` | CSV report (for data pipelines) |
**[API Reference](../../wiki/API-Reference):** Complete inputs, outputs, and data formats
---
## How It Works
```mermaid
---
config:
look: handDrawn
theme: neutral
---
flowchart TD
trigger(["Workflow Trigger"])
config["Parse configuration"]
fetch["Query GitHub REST API(repositories endpoint)"]
filter["Apply filter criteria"]
init["Initialize orphan branch"]
read["Deserialize previous state snapshot"]
compare["Compute delta metrics"]
stargazers["Fetch stargazers (starred_at)"]
history["Build real star history"]
forecast["Compute growth forecast"]
md["Markdown report"]
json["JSON dataset"]
csv["CSV report"]
svg["SVG badge"]
html["HTML digest"]
charts["SVG charts"]
commit["Git commit & push (data branch)"]
setout["Export action outputs"]
email{"SMTP configured?"}
send["Dispatch notification"]
trigger --> config --> fetch --> filter
filter --> init --> read --> compare
compare --> stargazers --> history --> forecast
forecast --> md & json & csv & svg & html & charts
md & json & csv & svg & html & charts --> commit --> setout --> email
email -->|Yes| send
style trigger fill:#e1f5ff,stroke:#01579b,stroke-width:2px
style config fill:#fff3e0,stroke:#e65100,stroke-width:2px
style fetch fill:#fff3e0,stroke:#e65100,stroke-width:2px
style filter fill:#fff3e0,stroke:#e65100,stroke-width:2px
style init fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style read fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style compare fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style stargazers fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style history fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style forecast fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style md fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style json fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style csv fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style svg fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style html fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style charts fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style commit fill:#fce4ec,stroke:#880e4f,stroke-width:2px
style setout fill:#fce4ec,stroke:#880e4f,stroke-width:2px
style email fill:#fce4ec,stroke:#880e4f,stroke-width:2px
style send fill:#fce4ec,stroke:#880e4f,stroke-width:2px
```
**[How It Works](../../wiki/How-It-Works):** Full architecture and execution pipeline
### How the charts read dates
The charts plot the **real historical curve**: every star is placed on the date it was actually given. Each stargazer carries a `starred_at` timestamp (GitHub's `application/vnd.github.star+json` media type), and the action reconstructs the cumulative star count over real time from those dates, so the timeline runs from a repo's very first star up to now, regardless of when you started running the action.
The per-run snapshots on the data branch are still kept for the report's delta tables and notifications ("how many stars changed since the last run"), but the charts themselves no longer depend on them.
One caveat: GitHub caps the stargazers listing at roughly **40,000 per repo** (oldest first), so for very large repos the most recent stars are unreachable. The reachable history is drawn accurately and the recent tail is bridged with a straight ramp up to the true current total, so the early curve stays accurate and the chart never goes flat at the end. Pair this with `smart-sampling` to keep the request cost bounded on big repos.
---
## Embedding in Your README
### Star Badge
```markdown
```
### Star History Chart
```markdown
```
> [!TIP]
> SVG charts automatically adapt to dark and light mode. No extra configuration needed - they use `prefers-color-scheme` to match the viewer's theme.
**[Viewing Reports](../../wiki/Viewing-Reports)**: All access methods (data branch, badges, outputs, email)
---
## Documentation
| Guide | Description |
| --------------------------------------------------------------------- | ----------------------------------------- |
| **[Getting Started](../../wiki/Getting-Started)** | Setup from token to first run |
| **[How It Works](../../wiki/How-It-Works)** | Execution flow and architecture |
| **[Configuration](../../wiki/Configuration)** | All options and settings |
| **[API Reference](../../wiki/API-Reference)** | Inputs, outputs, and data formats |
| **[Examples](../../wiki/Examples)** | Real-world workflow configurations |
| **[Star Trend Charts](../../wiki/Star-Trend-Charts)** | Chart types, embedding, and customization |
| **[Email Notifications](../../wiki/Email-Notifications)** | Built-in SMTP and external action setup |
| **[Viewing Reports](../../wiki/Viewing-Reports)** | Data branch, badges, outputs, raw data |
| **[Data Management](../../wiki/Data-Management)** | Storage, rotation, and manual management |
| **[Internationalization](<../../wiki/Internationalization-(i18n)>)** | Multi-language support |
| **[Personal Access Token](<../../wiki/Personal-Access-Token-(PAT)>)** | Classic and fine-grained token setup |
| **[Technical Stack](../../wiki/Technical-Stack)** | Technologies and design decisions |
| **[Known Limitations](../../wiki/Known-Limitations)** | Constraints and workarounds |
| **[Troubleshooting](../../wiki/Troubleshooting)** | Common issues and solutions |
## Support & Contributing
- **[Report bugs](../../issues/new?template=bug_report.yml)**
- **[Request features](../../issues/new?template=feature_request.yml)**
- **[Contributing guidelines](CONTRIBUTING.md)**
- **[Security policy](../../security/policy)**
If you find this project useful, consider supporting its development:
---
## Use of AI
This project uses AI assistance primarily for documentation purposes. AI tools (GitHub Copilot, Claude) were used to:
- Write and improve documentation (README, wiki pages)
- Generate boilerplate code and configuration files
- Assist with code reviews and suggestions
The core logic, architecture decisions, and implementation were developed by the maintainer. All AI-generated content has been reviewed and validated.
---
[AGPL-3.0](LICENSE) © Made with 🤘🏼 by [Ferran Buireu](https://github.com/fbuireu)