Trackeep/docs/GITHUB_OAUTH_SETUP.md

Unified GitHub App Setup

Trackeep self-hosted instances now use the unified controller at https://hq.trackeep.org for:

• GitHub sign-in
• GitHub App installation
• GitHub repo access used by backup flows

Self-Hosted Trackeep Instance

The self-hosted instance does not need any GitHub App credentials.

Required instance settings:

FRONTEND_URL=http://localhost:3000
PUBLIC_API_URL=http://localhost:9000
GITHUB_BACKUP_ROOT=./data/github-backups
GITHUB_BACKUP_TIMEOUT=10m

Flow:

1. GET /api/v1/auth/github redirects to https://hq.trackeep.org/auth/github
2. The controller redirects back to GET /api/v1/auth/control/callback?token=...
3. Trackeep validates that controller token against https://hq.trackeep.org/api/v1/auth/control/callback
4. Trackeep creates its own local JWT and redirects to /auth/callback?token=...

GitHub App installation:

1. Trackeep creates a local install state
2. Trackeep asks https://hq.trackeep.org/api/v1/github/app/install-url for a brokered install URL
3. GitHub redirects to https://hq.trackeep.org/auth/github/app/callback
4. The controller verifies the installation and redirects back to GET /api/v1/github/app/callback
5. Trackeep stores the installation ID locally

Unified Controller (Trackeep_OAUTH)

Trackeep_OAUTH owns the single shared GitHub App.

GitHub App settings:

• Homepage URL: your controller site URL
• User authorization callback URL: https://hq.trackeep.org/auth/github/callback
• Setup URL: https://hq.trackeep.org/auth/github/app/callback
• Expire user authorization tokens: enabled
• Request user authorization (OAuth) during installation: disabled

Required controller environment:

GITHUB_APP_CLIENT_ID=your_github_app_client_id
GITHUB_APP_CLIENT_SECRET=your_github_app_client_secret
GITHUB_APP_SLUG=trackeep
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_REDIRECT_URL=https://hq.trackeep.org/auth/github/callback
DEFAULT_CLIENT_URL=https://app.trackeep.org
SERVICE_DOMAIN=https://hq.trackeep.org

Permissions:

• Account: Email addresses -> Read-only
• Repository: Metadata -> Read-only
• Repository: Contents -> Read-only