Skip to main content

​
Quick Start Guide

This guide will have you tracking stars across all your repositories in under 5 minutes.
1

Create a Personal Access Token

A PAT is required because the default GITHUB_TOKEN cannot access your full repository list.
  1. Navigate to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click Generate new token → Generate new token (classic)
  3. Give it a descriptive name like Star Tracker
  4. Select expiration (recommend No expiration for continuous tracking)
  5. Select scopes:
    • For public repositories only: public_repo
    • For all repositories: repo (full control)
  6. Click Generate token and copy it immediately
Store your token securely! You won’t be able to see it again. If you lose it, you’ll need to generate a new one.
2

Add Token as Repository Secret

  1. Go to your repository on GitHub
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Name: GITHUB_STAR_TRACKER_TOKEN
  5. Value: Paste your PAT from step 1
  6. Click Add secret
If you want to use this action across multiple repositories, consider adding it as an organization secret instead.
3

Create the Workflow File

Create a new file in your repository at .github/workflows/star-tracker.yml:
name: Track Stars

on:
  schedule:
    - cron: '0 0 * * *'  # Run daily at midnight UTC
  workflow_dispatch:      # Allow manual triggering

permissions:
  contents: write         # Required to commit to data branch

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - uses: fbuireu/github-star-tracker@v1
        with:
          github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}
The workflow_dispatch trigger allows you to manually run the action from the Actions tab, perfect for testing!
4

Commit and Push

git add .github/workflows/star-tracker.yml
git commit -m "Add Star Tracker workflow"
git push
5

Run the Action Manually

For your first run, trigger it manually to see immediate results:
  1. Go to your repository on GitHub
  2. Click the Actions tab
  3. Select Track Stars from the left sidebar
  4. Click Run workflow → Run workflow
  5. Wait 30-60 seconds for completion
The first run initializes the data branch and creates the baseline snapshot. Subsequent runs will show deltas and trends.
6

View Your Reports

After the workflow completes:
  1. Go to your repository’s branches
  2. Switch to the star-tracker-data branch
  3. Explore the generated files:
    • README.md - Markdown report with summary tables
    • stars-badge.svg - Embeddable badge with star count
    • history.json - Raw historical data
    • charts/ - Animated SVG charts

​
What Just Happened?

Your workflow just:
  1. Fetched all repositories accessible by your PAT
  2. Counted the stars on each repository
  3. Generated a snapshot with timestamp and metadata
  4. Created reports, charts, and a badge
  5. Committed everything to the star-tracker-data branch

​
Embedding Reports in Your README

​
Star Count Badge

Add a live-updating badge to your repository README: 
![Total Stars](https://raw.githubusercontent.com/YOUR_USERNAME/YOUR_REPO/star-tracker-data/stars-badge.svg)
Replace YOUR_USERNAME and YOUR_REPO with your actual GitHub username and repository name.

​
Star History Chart

Embed the animated star history chart: 
![Star History](https://raw.githubusercontent.com/YOUR_USERNAME/YOUR_REPO/star-tracker-data/charts/star-history.svg)
Charts automatically adapt to the viewer’s color scheme (light/dark mode) using CSS media queries!

​
Testing the Setup

To verify everything is working: 
# Trigger a manual workflow run
gh workflow run star-tracker.yml

# Watch the workflow execute
gh run watch

​
Common Quickstart Issues

This means your workflow doesn’t have contents: write permission. Make sure you’ve added:
permissions:
  contents: write
at the workflow level (not in the job).
Your PAT is invalid, expired, or incorrectly stored. Verify:
  1. The secret name is exactly GITHUB_STAR_TRACKER_TOKEN
  2. The token hasn’t expired
  3. The token has the correct scopes (repo or public_repo)
The action found no repositories matching the default filters. This could mean:
  • Your PAT only has public_repo scope but you have no public repos
  • All your repositories are forks (excluded by default)
  • You need to add visibility: all if tracking private repos

​
Next Steps

Now that you have the basics working, explore more advanced features:

Configuration Options

Filter repositories, customize reports, set thresholds, and more

Email Notifications

Get notified when star counts change

Chart Customization

Customize chart appearance and behavior

Advanced Examples

Complex workflows with filtering and chaining

​
Scheduling Best Practices

Recommended Schedule: Run daily at off-peak hours to minimize API rate limit impact.
Common Schedules
on:
  schedule:
    # Daily at midnight UTC
    - cron: '0 0 * * *'
    
    # Every Monday at 9 AM UTC
    - cron: '0 9 * * 1'
    
    # Twice daily (morning and evening UTC)
    - cron: '0 6,18 * * *'
    
    # Weekly on Sunday at midnight
    - cron: '0 0 * * 0'
Choose a frequency that balances freshness with API quota consumption. For most users, daily tracking is ideal.

​
Getting Help

If you run into issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us