All guides

Guides · Setup

Self-hosting gbar's OAuth app

Register your own GitHub OAuth app, paste one client ID, and run gbar with zero third-party servers.

4 min read

gbar is free to self-host. It authenticates with GitHub's OAuth device flow, which needs only a public client ID: no server, no client secret, no callback endpoint. Register your own OAuth app once, paste the client ID into Settings, and nothing sits between you and the GitHub API.

Option A: your own OAuth app (recommended)

  1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App (github.com/settings/developers)
  2. Fill in anything for name and homepage, e.g. gbar (personal). The callback URL is required by the form but unused by device flow; put http://localhost
  3. On the app's page, check "Enable Device Flow" and save
  4. Copy the Client ID; it's public, there is no secret to manage
  5. In gbar: Settings → Account → Sign in with GitHub, paste the client ID, and enter the one-time code at github.com/login/device

Step 3 is the one people miss: device flow is off by default on new OAuth apps. If sign-in fails immediately, check that box first.

GitHub Enterprise

Register the OAuth app on your Enterprise instance instead, then set the API base URL of your host in Settings → Advanced:

settings · api base url
https://ghe.example.com/api/v3

Option B: personal access token

Zero-OAuth setup: create a classic token at github.com/settings/tokens with the repo scope (add notifications if you want the inbox features), then use Settings → Account → Use a token instead.

Either way, credentials are stored in the macOS Keychain, never in plaintext on disk. The canonical reference lives in the repo at docs/SELF-HOST.md.


Rather build the whole app yourself too? Building gbar from source. Self-host builds ship a blank client ID and prompt at runtime.