GitHub OAuth

Glyph supports two unrelated GitHub integrations:

1. GitHub OAuth login - users sign into Glyph itself with their GitHub account
2. Connected GitHub accounts (PAT) - users connect one or more GitHub accounts to import private repositories

This page covers the first. For the second, see Connecting Accounts.

OAuth login is optional. Without it, users sign in with email + password.

Why enable OAuth login?

• Faster onboarding for teams already using GitHub
• One fewer password to remember
• Familiar SSO-like experience

The downside: every user needs a GitHub account, which may not suit closed teams or external collaborators.

Creating the OAuth App

1. Go to github.com/settings/developers.
2. Click OAuth Apps → New OAuth App.
3. Fill in:
   • Application name: Glyph (or anything)
   • Homepage URL: http://localhost:3000 (your FRONTEND_URL)
   • Authorization callback URL: http://localhost:8000/api/auth/github/callback (your APP_URL + /api/auth/github/callback)
4. Click Register application.
5. Copy the Client ID.
6. Click Generate a new client secret and copy the secret immediately (it's shown once).

Configuring Glyph

In your .env:

GITHUB_CLIENT_ID=<your client id>
GITHUB_CLIENT_SECRET=<your client secret>

Restart the backend:

docker compose restart backend

The login page now shows a Sign in with GitHub button.

How sign-in works

1. User clicks Sign in with GitHub.
2. Browser is redirected to GitHub for consent.
3. GitHub redirects back to APP_URL/api/auth/github/callback?code=....
4. Backend exchanges the code for an access token, fetches the user's GitHub profile, and creates or matches a Glyph user record by email.
5. Backend issues a JWT and redirects to the frontend.

The OAuth access token from this flow is used only for authentication - it's not stored. To import private repositories, the user still needs to add a Personal Access Token.

Production callback URL

When deploying behind a reverse proxy, update both:

• The OAuth App's callback URL on github.com (e.g. https://api.glyph.example.com/api/auth/github/callback)
• APP_URL in .env (e.g. https://api.glyph.example.com)

The two must match exactly - including scheme, host, port, and path. A common gotcha is mismatched trailing slashes.

Disabling OAuth

To disable, leave GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET empty (or comment them out). The login page hides the GitHub button automatically.