-
-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Solutions for common issues with GitHub Star Tracker.
Cause: Invalid or expired Personal Access Token.
Fix:
- Generate a new token at GitHub Settings > Tokens
- Ensure the token has
reposcope (for private repos) orpublic_reposcope (public only) - Update the secret in your repo: Settings > Secrets and variables > Actions
- Re-run the workflow
Cause: Using the default GITHUB_TOKEN instead of a Personal Access Token.
Fix: The default GITHUB_TOKEN cannot list repositories across your account. You must create a Personal Access Token. See Personal Access Token (PAT).
Cause: The secret name in the workflow doesn't match the secret stored in the repo.
Fix: Verify the secret name matches exactly:
# In workflow
github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}Must match the secret name GITHUB_STAR_TRACKER_TOKEN in Settings > Secrets.
Cause: The workflow doesn't have write permission to push to the data branch.
Fix: Add permissions to your workflow:
permissions:
contents: writeCause: The token doesn't have the workflow scope, and the data branch somehow contains workflow files.
Fix: This shouldn't happen with normal usage. If it does, delete the data branch and let the action recreate it:
git push origin --delete star-tracker-dataExpected behavior. The first run creates the data branch and records initial star counts with delta: 0. Charts require 2+ runs, forecasts require 3+ runs.
Possible causes:
- Token doesn't have access to the repos you expect
- All repos are filtered out by
visibility,min-stars,exclude-repos, or other filters - Only forks/archived repos exist and
include-forks/include-archivedarefalse
Fix: Check your filters. Try running with minimal config first:
- uses: fbuireu/github-star-tracker@v1
with:
github-token: ${{ secrets.GITHUB_STAR_TRACKER_TOKEN }}Fix: Delete the branch and let the action recreate it:
git push origin --delete star-tracker-dataCause: Some Git tools show orphan branches in comparisons.
Fix: This is cosmetic. The data branch has no common history with main and cannot be merged.
Possible causes:
- First run (need 2+ snapshots for charts)
include-charts: false- Only 1 snapshot in history
Fix: Wait for the second run, or trigger manually with workflow_dispatch.
Cause: Forecasts require at least 3 snapshots.
Fix: Run the workflow 3+ times to accumulate enough data.
Possible causes:
- No star changes detected (the action skips the commit)
- Workflow failed silently
Fix: Check the workflow run logs in Actions tab. If stars haven't changed, no commit is made — this is expected.
Cause: Using the wrong URL or branch name.
Fix: Use the correct raw URL format:
Replace star-tracker-data with your data-branch value if customized.
Checklist:
- Check your spam/junk folder
- Verify SMTP credentials are correct
- For Gmail: ensure you're using an app password (not your account password) — requires 2FA enabled
- Check that
stars-changedistrue(no email sent if nothing changed, unlesssend-on-no-changes: true) - Check the workflow run logs for email-related warnings
Common causes:
- Gmail: using account password instead of app password
- Incorrect username or password
- 2FA not enabled (required for Gmail app passwords)
Fix for Gmail:
- Enable 2-factor authentication
- Go to App Passwords
- Generate a new app password for "Mail"
- Use the 16-character generated password as
smtp-password
Fix: Add a condition to your email step:
- name: Send email
if: steps.tracker.outputs.stars-changed == 'true'
uses: dawidd6/action-send-mail@v9Or use notification-threshold with the built-in email to control frequency.
Possible causes:
include-charts: false- Less than 2 snapshots
- Email client blocking external images (QuickChart.io URLs)
Fix: Click "Show images" or "Load remote content" in your email client.
Possible causes:
- GitHub Actions disables scheduled workflows after 60 days of repo inactivity
- Cron syntax error
- Workflow file is not on the default branch
Fix:
- Push a commit or manually trigger the workflow to re-enable it
- Validate cron syntax at crontab.guru
- Ensure the workflow file is in
.github/workflows/on your default branch
Possible causes:
- No star changes detected (expected — no commit is made)
- All repos filtered out
Fix: Check the workflow run logs. The action logs which repos are tracked and any filtering that occurred.
Cause: Your PAT only has public_repo scope but is trying to access private forks.
Fix: Use repo scope on the PAT if you need access to private repositories.
Cause: Wrong path or the file doesn't exist.
Fix: The default path is star-tracker.yml at the repo root. If using a custom path:
with:
config-path: '.github/star-tracker.yml'Ensure the file exists at that path on the branch where the workflow runs.
Cause: Action inputs take precedence over config file values.
Fix: If you set an option in both the workflow and the config file, the workflow value wins. Remove the workflow input to let the config file value apply.
See Configuration > Precedence.
Cause: Unsupported locale value.
Fix: Use one of: en, es, ca, it. The action falls back to en with a warning.
Cause: Regex patterns in exclude-repos must be wrapped in /:
# Correct
exclude-repos: '/^test-.*/'
# Incorrect — treated as literal string
exclude-repos: '^test-.*'If your issue isn't covered here:
- Check the workflow run logs for detailed error messages
- Open an issue at github-star-tracker/issues
- Include: workflow file, error logs, and expected vs actual behavior
- Configuration — All available options
- Known Limitations — Current constraints
- Examples — Working configurations