Known Limitations

​

GitHub API Limitations

​

Rate Limits

• Authenticated requests: 5,000 requests per hour
• Unauthenticated requests: 60 requests per hour

• Typical usage (without stargazer tracking): 1-5 API requests per run
• With stargazer tracking: 1-5 + (1 per repository) API requests
• Users with 100+ repositories and stargazer tracking enabled may approach rate limits if running very frequently

1. Disable stargazer tracking if not needed:
   track-stargazers: false
   
2. Run less frequently:
   on:
     schedule:
       - cron: '0 0 * * 0'  # Weekly instead of daily
   
3. Reduce the number of tracked repositories:
   min-stars: '10'  # Only track popular repos
   

​

Stargazer History Limitation

• You can only see new stargazers since the last run
• If someone stars and unstars between runs, they won’t appear in reports
• No way to recover stargazers from before you started tracking

• Run the action frequently (daily or more) to minimize gaps
• Accept this as an inherent limitation of the GitHub API

​

Repository Count Pagination

• Users with 1,000+ repositories will require 10+ API requests just to list all repos
• Slightly slower execution for users with many repositories

• Use filtering to reduce the number of repositories:
  visibility: 'public'  # Exclude private repos
  min-stars: '5'        # Only track repos with engagement
  include-archived: false
  include-forks: false
  

​

Token Limitations

​

Default GITHUB_TOKEN Not Supported

• You must create a Personal Access Token (PAT)
• Additional setup step required

• Classic: repo or public_repo
• Fine-grained: Repository access with Contents + Metadata read permissions

​

Organization Repository Access

• Some organizations don’t support fine-grained tokens yet
• Fine-grained tokens require explicit organization approval
• Classic tokens may be required for some enterprise setups

• Use Classic PAT with repo scope for organization repositories
• Request organization admin to approve fine-grained token access

​

Data Storage Limitations

​

Git Branch Storage

• Maximum practical size: ~50 MB (GitHub’s repository size recommendations)
• All data is version-controlled (no selective deletion)
• Branch must be publicly accessible for badge embedding

• Users with thousands of repositories and extended history (100+ snapshots) might approach practical size limits
• Typical user with 50 repositories and 52 snapshots: < 2 MB

1. Reduce history retention:
   max-history: '26'  # 6 months instead of 1 year
   
2. Disable stargazer tracking (larger data footprint):
   track-stargazers: false
   
3. Filter repositories:
   min-stars: '10'
   

​

Private Repository Badge Embedding

• SVG badges/charts won’t render if the data branch is private
• Can only be viewed within the same private repository

1. Make the data branch repository public (while keeping source code private)
2. Host charts externally (e.g., upload to a public CDN)
3. Use outputs to post data to external services instead of embedding

​

Feature Limitations

​

Stargazer Historical Tracking

• Only detects new stargazers since last run
• No historical timeline of individual stars
• Cannot build a “who starred when” timeline retroactively

• Start tracking as early as possible to build history going forward
• Use GitHub’s built-in Insights > Traffic for some historical data (limited retention)

​

No Unstar Detection

• Reports show “Lost Stars: 5” but not which users
• Can infer from stargazer list changes, but not 100% reliable

• Accept aggregate unstar counts as sufficient
• Run very frequently (hourly) to narrow down timeframe

​

Chart Customization

• Fixed color schemes (dark/light mode)
• Fixed chart dimensions and layouts
• No custom chart types beyond the three provided

1. Use CSV/JSON outputs to generate custom charts:
   - uses: fbuireu/github-star-tracker@v1
     id: tracker
   
   - name: Generate Custom Chart
     run: |
       echo '${{ steps.tracker.outputs.report-csv }}' > data.csv
       # Use your preferred charting tool
   
2. Request features via feature request

​

Language Support

• English (en)
• Spanish (es)
• Catalan (ca)
• Italian (it)

​

Workflow Limitations

​

Execution Time

• Without stargazer tracking: 1-2 minutes
• With stargazer tracking (50 repos): 3-5 minutes
• With stargazer tracking (100+ repos): 5-10 minutes

• Consumes GitHub Actions minutes
• May timeout on free tier if you have hundreds of repositories with stargazer tracking

track-stargazers: false  # Much faster
top-repos: '5'           # Fewer charts to generate

​

Scheduling Precision

• Workflow won’t run at exactly the scheduled time
• May not run at all if GitHub Actions is experiencing issues

• Accept approximate scheduling (not critical for star tracking)
• Use workflow_dispatch for manual triggering when needed

​

Concurrent Runs

concurrency:
  group: star-tracker
  cancel-in-progress: true  # Cancel previous run if new one starts

​

Platform Limitations

​

GitHub Enterprise Server (GHES)

• GHES 3.0 or later recommended
• API compatibility varies by version

• Older GHES installations may have missing API endpoints
• Some newer GitHub features may not be available

• Upgrade GHES to latest version
• Contact maintainers if specific issues arise on your GHES version

​

Self-Hosted Runners

jobs:
  track:
    runs-on: ubuntu-latest  # Use GitHub-hosted runner

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

​

Email Limitations

​

SMTP Authentication

• Gmail requires App Passwords (not account password)
• Corporate email servers may block external SMTP
• 2FA-enabled accounts need special configuration

1. Gmail: Use App Passwords
2. Corporate email: Use external SMTP relay services
3. Alternative: Use GitHub Actions notification actions instead of built-in SMTP

​

HTML Email Rendering

• Plain text fallback may not be as visually appealing
• Images from private repositories won’t load

• Accept plain text rendering in strict email clients
• Use markdown output for better plain text experience

​

Security Limitations

​

Token Storage

• Anyone with repository admin access can view/modify secrets
• Tokens cannot be scoped to specific workflows

• Use fine-grained PATs with minimal permissions
• Regularly rotate tokens
• Use organization-level secrets for shared access control

​

Data Privacy

• Star counts and stargazer lists are public if data branch is public
• Cannot embed badges from private repositories externally

• Keep entire repository private if you need private star tracking
• Only track public repositories if privacy is a concern
• Use track-stargazers: false to avoid storing user information

​

Future Improvements