Which token permissions does Star Trail need?

To pull star data, Star Trail uses a fine-grained personal access token that you create on GitHub. Fine-grained tokens are scoped to specific repositories and specific permissions, so you're never handing over blanket access to your whole account. You stay in control of what the token can touch.

The permissions to grant

When you create the token, scroll to Permissions → Repository permissions and set these two:

• Metadata → Read-only

  GitHub requires this on every fine-grained token that touches a repository. It covers the basics — the repo's name, description, and other public details.

• Contents → Read and write

  This is the one that catches people off guard. The stargazers endpoint now requires Contents write access — that's how GitHub verifies you're a collaborator, and read-only is no longer accepted.

Wait — why does reading stars need write access?

It's a fair question, and it trips almost everyone up. Reading a star count feels like it should only need read access. But GitHub uses the Contents write permission as a proxy for “this person is actually a collaborator on the repo” — it's a gatekeeping check, not something Star Trail uses to change your files.

In practice, read-only tokens get rejected by the stargazers endpoint outright, so the write permission is the only combination that works today. To be clear: Star Trail never writes anything to your repository. It only reads star data. The write permission is there because GitHub demands it for the collaborator check, not because we use it.

Where does the token go?

Once you paste your token, it's encrypted with AES-256 and stored server-side only. It's never sent back to the browser and never exposed in any embed or chart. If you ever want to rotate it, you can update the token from your repository's page at any time.

And because you're using a fine-grained token scoped to a single repository, the worst-case blast radius stays tiny — you can revoke it from GitHub whenever you like, and Star Trail loses access instantly.