Skip to main content

​
Purpose

Starcat uses your GitHub identity to pull Stars, read public repository metadata, and Unstar when you explicitly ask. It does not take your GitHub password. Credentials go into the macOS Keychain. Sign-in only creates a session. The repository list still needs the Sync tap in Quickstart.

​
How to sign in

Sign-in screen: primary GitHub button and Other sign-in methods

Screenshot TODO · images/screenshots/getting-started/login.webp

  1. Tap Sign in with GitHub
  2. The system browser opens GitHub’s authorize page
  3. After you approve, you return to Starcat
The App Store build uses ASWebAuthenticationSession. Device Flow (which would launch an external browser) and PAT-as-primary-login are blocked there: hidden in UI and rejected in the auth layer.

​
Direct: Device Flow and PAT

Direct also offers Device Flow (when the OAuth callback is awkward) and a PAT:
1

Create a token

GitHub Developer settings → Personal access tokens.
2

Scopes

  • Classic: typically read:user and public_repo
  • Fine-grained: enough read access for profile and public Stars / repo metadata
3

Paste

Expand Other sign-in methods on the login screen and paste the token.
One active session uses one credential. Sign out before you switch methods.

​
What Starcat asks for

Reading a README in daily use does not scan your private work repos.
Unstar calls the GitHub Unstar API only when you trigger it from detail or batch actions. The notification inbox needs notification permission. Activity prompts you to re-authorize when it is missing. See Activity.

​
GitHub App (My Projects)

Private / Internal repositories under My Projects need a separate GitHub App installation (org / repo scope). Public project listing can still use the main OAuth / PAT session. If private projects are missing, finish the in-app App install and sync again.

​
Multiple accounts

  • One active GitHub account at a time
  • Switch: sidebar avatar → sign out → sign in with the other account
  • Local data is isolated per account; tags and notes return when you switch back
If work and personal Stars must stay strictly apart, use separate macOS users or accept sign-out switching. Do not stack two tokens in one session.

​
Notes

  • Never paste a PAT into chat or git
  • On 401, sign in again or rotate the token
  • If a corporate network blocks the callback, Direct users should try PAT or Device Flow
  • An expired token does not delete local tags; it only blocks remote fetches until you refresh credentials
Last modified on August 25, 2026