Installation

Prerequisites

Before installing GitHub Star Tracker, ensure you have:

A GitHub account with repositories to track
Repository access to create Actions workflows
Permissions to create Personal Access Tokens
contents: write permission in your workflow

The action requires Node.js 24+, but this is automatically provided by GitHub Actions runners. No local installation needed.

Installation Steps

Step 1: Create a Personal Access Token

The default GITHUB_TOKEN provided by GitHub Actions cannot access the full list of repositories for an authenticated user. You must create a Personal Access Token (PAT).

Why is a PAT required?The GitHub API requires authentication to list all repositories accessible to a user. The automatic GITHUB_TOKEN is scoped to the current repository only and cannot query the /user/repos endpoint needed by this action.

Creating a Classic Token (Recommended)

Navigate to Token Settings

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

Generate New Token

Click Generate new token → Generate new token (classic)

Configure Token

Note: Give your token a descriptive name

GitHub Star Tracker - YOUR_REPO_NAME

Expiration: Choose based on your needs

No expiration - Recommended for continuous tracking
90 days - Good balance of security and maintenance
Custom date - For specific tracking periods

Scopes: Select based on repository visibility

Public Repositories Only
All Repositories
Organization Repositories

Select only:

✅ public_repo - Access public repositories

Select:

✅ repo - Full control of private repositories
- This automatically includes public_repo

Select:

✅ repo - Full control of private repositories
✅ read:org - Read org and team membership (optional)

Generate and Copy

Click Generate token at the bottom
Copy the token immediately - you won’t see it again!
Store it temporarily in a secure location

Security Best Practice: Never commit your PAT to version control or share it publicly. Always use GitHub Secrets.

Alternative: Fine-Grained Personal Access Token

Fine-grained tokens offer more precise permissions but require additional setup:

Create Fine-Grained Token

Navigate to Personal access tokens → Fine-grained tokens

Configure Access

Repository access: Choose one

All repositories
Only select repositories
Public repositories (this account)

Set Permissions

Under Repository permissions:

Contents: Read and write (for committing to data branch)
Metadata: Read-only (automatically included)

Step 2: Add Token as Secret

Store your PAT securely as a repository or organization secret.

For a Single Repository

Navigate to Repository Settings

Go to your repository → Settings → Secrets and variables → Actions

Create New Secret

Click New repository secret

Add Secret Details

Name:

GITHUB_STAR_TRACKER_TOKEN

Value: Paste your PAT from Step 1Click Add secret

For Multiple Repositories (Organization)

Navigate to Organization Settings

Go to your organization → Settings → Secrets and variables → Actions

Create Organization Secret

Click New organization secret

Configure Secret

Name:

GITHUB_STAR_TRACKER_TOKEN

Value: Paste your PATRepository access: Choose which repos can use this secret

All repositories
Private repositories
Selected repositories

Click Add secret

Step 3: Create Workflow File

Create the workflow file that will run the Star Tracker action.

Create Workflow Directory

In your repository, create the workflows directory if it doesn’t exist:

mkdir -p .github/workflows

Create Workflow File

Create .github/workflows/star-tracker.yml with your preferred configuration:

name: Track Stars

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight UTC
  workflow_dispatch:      # Manual trigger

permissions:
  contents: write

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

Commit and Push

git add .github/workflows/star-tracker.yml
git commit -m "feat: add GitHub Star Tracker workflow"
git push origin main

Step 4: Initial Run

Run the action for the first time to initialize the data branch.

Via GitHub UI

Navigate to your repository on GitHub
Click the Actions tab
Select Track Stars from the workflows list
Click Run workflow → Run workflow
Wait for the run to complete (typically 30-60 seconds)

Via GitHub CLI

# Trigger workflow
gh workflow run star-tracker.yml

# Watch execution
gh run watch

# View latest run logs
gh run view --log

The first run creates the star-tracker-data branch and generates the initial snapshot. Subsequent runs will show deltas and trends.

Step 5: Verify Installation

Confirm everything is working correctly:

Check Workflow Status

Go to Actions tab in your repository
Verify the workflow completed successfully (green checkmark)
Review the logs for any warnings or errors

Inspect Data Branch

Switch to the star-tracker-data branch
Verify these files exist:
- README.md - Markdown report
- stars-badge.svg - Badge
- history.json - Historical data
- charts/ directory (if charts enabled)

git fetch
git checkout star-tracker-data
ls -la

View Generated Report

Open README.md on the data branch to see your first report:

cat README.md

Or view it on GitHub:

https://github.com/YOUR_USERNAME/YOUR_REPO/blob/star-tracker-data/README.md

Configuration Options

Core Settings

Input	Default	Description
`github-token`	Required	PAT with `repo` or `public_repo` scope
`data-branch`	`star-tracker-data`	Branch name for storing data
`max-history`	`52`	Maximum snapshots to retain
`locale`	`en`	Report language (`en`, `es`, `ca`, `it`)

Filtering Options

Input	Default	Description
`visibility`	`all`	`public`, `private`, `all`, or `owned`
`min-stars`	`0`	Minimum stars required to track
`include-archived`	`false`	Include archived repositories
`include-forks`	`false`	Include forked repositories
`exclude-repos`	-	Comma-separated names or regex patterns
`only-repos`	-	Only track these specific repositories

Chart and Report Options

Input	Default	Description
`include-charts`	`true`	Generate SVG charts
`top-repos`	`10`	Number of top repos in charts
`track-stargazers`	`false`	Track individual stargazers

Notification Options

Input	Default	Description
`smtp-host`	-	SMTP server hostname
`smtp-port`	`587`	SMTP server port
`smtp-username`	-	SMTP authentication username
`smtp-password`	-	SMTP authentication password
`email-to`	-	Recipient email address
`email-from`	`GitHub Star Tracker`	Sender name
`notification-threshold`	`0`	`0` (always), number, or `auto`
`send-on-no-changes`	`false`	Email even with no changes

For detailed configuration documentation, see the Configuration Reference.

Advanced Setup

Using a Configuration File

For complex setups, use a YAML configuration file instead of inline inputs:

Create Config File

Create star-tracker.yml in your repository root:

star-tracker.yml

visibility: public
locale: en
includeCharts: true
trackStargazers: true
dataBranch: star-tracker-data
maxHistory: 52
topRepos: 10
minStars: 5
includeArchived: false
includeForks: false
excludeRepos:
  - test-repo
  - /^demo-.*/
notificationThreshold: auto

Reference in Workflow

- uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}
    config-path: star-tracker.yml

Workflow inputs override config file settings, allowing environment-specific customization.

GitHub Enterprise Server

For GitHub Enterprise Server (GHES) instances:

- uses: fbuireu/github-star-tracker@v1
  with:
    github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}
    github-api-url: https://github.example.com/api/v3

The API URL is auto-detected on GHES runners, so this input is typically only needed for custom endpoints.

Troubleshooting Installation

Error: Resource not accessible by integration

Cause: Missing contents: write permissionSolution: Add permissions to your workflow:

permissions:
  contents: write

Error: Bad credentials

Cause: Invalid or expired PATSolutions:

Verify the secret name matches exactly: GITHUB_STAR_TRACKER_TOKEN
Check token hasn’t expired in GitHub Settings
Regenerate token with correct scopes (repo or public_repo)
Update the secret value in repository settings

Error: No repositories found

Cause: Filters excluding all repositoriesSolutions:

Remove restrictive filters temporarily: visibility: all
Check PAT has access to your repositories
For private repos, ensure PAT has repo scope (not just public_repo)
Verify include-forks and include-archived settings

Charts not generating

Cause: Insufficient historical dataSolution: Charts require at least 2 snapshots. Run the action again or wait for next scheduled run.

Data branch not created

Cause: Permissions or workflow configuration issueSolutions:

Verify contents: write permission is set
Check workflow logs for error messages
Ensure PAT has repository access
Try running workflow manually first

Next Steps

Configuration Guide

Explore all configuration options in detail

Example Workflows

See real-world configuration examples

Email Notifications

Set up SMTP notifications for star changes

Viewing Reports

Learn how to access and embed your reports

Getting Help

If you encounter issues during installation:

Check the Troubleshooting Guide for detailed solutions
Review GitHub Discussions for community help
Search or open an issue on GitHub
Review the API Reference for input/output specifications

Get Started

Core Concepts

Configuration

Features

Guides

Prerequisites

Installation Steps

Step 1: Create a Personal Access Token

Creating a Classic Token (Recommended)

Alternative: Fine-Grained Personal Access Token

Step 2: Add Token as Secret

For a Single Repository

For Multiple Repositories (Organization)

Step 3: Create Workflow File

Step 4: Initial Run

Via GitHub UI

Via GitHub CLI

Step 5: Verify Installation

Configuration Options

Core Settings

Filtering Options

Chart and Report Options

Notification Options

Advanced Setup

Using a Configuration File

GitHub Enterprise Server

Troubleshooting Installation

Next Steps

Configuration Guide

Example Workflows

Email Notifications

Viewing Reports

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Features

Guides

​Prerequisites

​Installation Steps

​Step 1: Create a Personal Access Token

​Creating a Classic Token (Recommended)

​Alternative: Fine-Grained Personal Access Token

​Step 2: Add Token as Secret

​For a Single Repository

​For Multiple Repositories (Organization)

​Step 3: Create Workflow File

​Step 4: Initial Run

​Via GitHub UI

​Via GitHub CLI

​Step 5: Verify Installation

​Configuration Options

​Core Settings

​Filtering Options

​Chart and Report Options

​Notification Options

​Advanced Setup

​Using a Configuration File

​GitHub Enterprise Server

​Troubleshooting Installation

​Next Steps

Configuration Guide

Example Workflows

Email Notifications

Viewing Reports

​Getting Help

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Step 1: Create a Personal Access Token

Creating a Classic Token (Recommended)

Alternative: Fine-Grained Personal Access Token

Step 2: Add Token as Secret

For a Single Repository

For Multiple Repositories (Organization)

Step 3: Create Workflow File

Step 4: Initial Run

Via GitHub UI

Via GitHub CLI

Step 5: Verify Installation

Configuration Options

Core Settings

Filtering Options

Chart and Report Options

Notification Options

Advanced Setup

Using a Configuration File

GitHub Enterprise Server

Troubleshooting Installation

Next Steps

Getting Help