Skip to content

Getting Started

Jump to bottom
Ferran Buireu edited this page Feb 15, 2026 · 3 revisions

This guide walks you through setting up GitHub Star Tracker from scratch.

Prerequisites

  • A GitHub account with at least one repository
  • GitHub Actions enabled in your repository

Step 1: Create a Personal Access Token

GitHub Star Tracker requires a Personal Access Token (PAT) because the default GITHUB_TOKEN cannot list repositories across your account.

  1. Go to GitHub Settings > Tokens (classic)
  2. Click "Generate new token (classic)"
  3. Configure:
    • Note: GitHub Star Tracker
    • Expiration: 90 days (recommended)
    • Scopes: repo (private + public) or public_repo (public only)
  4. Click "Generate token" and copy it immediately
  5. In your repository, go to Settings > Secrets and variables > Actions
  6. Click "New repository secret":
    • Name: GITHUB_STAR_TRACKER_TOKEN
    • Value: paste your PAT

For detailed instructions (including fine-grained tokens), see Personal Access Token (PAT).

Step 2: Create the Workflow

Create .github/workflows/star-tracker.yml in your repository:

name: Track Stars

on:
  schedule:
    - cron: '0 0 * * *' # Daily at midnight UTC
  workflow_dispatch: # Allow manual triggers

permissions:
  contents: write

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - uses: fbuireu/github-star-tracker@v1
        with:
          github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}

That's the minimal setup. The action will track all your repositories with default settings.

Step 3: Run the Action

First Run (Manual)

  1. Go to your repository's Actions tab
  2. Select "Track Stars" from the workflow list
  3. Click "Run workflow" > "Run workflow"
  4. Wait for completion (~10-30 seconds)

Verify It Worked

After the first run:

  1. Go to your repository's branch selector and look for star-tracker-data
  2. Navigate to https://github.com/YOUR_USER/YOUR_REPO/tree/star-tracker-data
  3. You should see:
    • README.md — Full Markdown report
    • stars-data.json — Historical data (JSON)
    • stars-badge.svg — Star count badge

Charts and forecasts require at least 2 runs to have enough data points.

Step 4: Add Badge to Your README (Optional)

Display your total star count in your main README:

![Total Stars](https://raw.githubusercontent.com/YOUR_USER/YOUR_REPO/star-tracker-data/stars-badge.svg)

Link to the full report:

[![Total Stars](https://raw.githubusercontent.com/YOUR_USER/YOUR_REPO/star-tracker-data/stars-badge.svg)](https://github.com/YOUR_USER/YOUR_REPO/tree/star-tracker-data)

Embed the star history chart:

![Star History](https://raw.githubusercontent.com/YOUR_USER/YOUR_REPO/star-tracker-data/charts/star-history.svg)

What Happens Next

  • The action runs on your configured schedule (daily by default)
  • Each run compares current stars with the previous snapshot
  • Reports and charts are updated on the star-tracker-data branch
  • After 2+ runs, animated SVG charts appear in the charts/ directory
  • After 3+ runs, growth forecasts are computed

Next Steps

Clone this wiki locally