GitHub Authentication

Set up GitHub authentication for repository access — browser OAuth, device flow, and local token reuse.

Authentication Methods

OpenLinear tries methods in this priority order:

1. GitHub CLI reuse

   If GitHub CLI (gh) is already authenticated on your machine, openlinear github login reuses that local token automatically.

2. Browser-based OAuth

   If OPENLINEAR_GITHUB_CLIENT_SECRET is set, OpenLinear starts a temporary callback server on http://localhost:<port>/callback, opens GitHub in your browser, and stores the token locally.

3. Device flow fallback

   If no client secret is configured, OpenLinear falls back to GitHub’s device flow — you visit a URL and enter a code.

---

Commands

Login

openlinear github login

Auto-selects the best available method. Force a specific flow:

openlinear github login --browser   # Force browser OAuth
openlinear github login --device    # Force device flow

Status

openlinear github status

Shows whether GitHub is connected and which authentication source is active.

Identity

openlinear github whoami

Displays the authenticated GitHub username.

Logout

openlinear github logout

Removes stored GitHub credentials from your machine.

---

Environment Variables

These are only needed for the browser-based OAuth flow. Device flow works without any configuration.

Variable	Required	Description
OPENLINEAR_GITHUB_CLIENT_SECRET	For browser flow	GitHub OAuth app client secret
OPENLINEAR_GITHUB_CALLBACK_HOST	No	Callback host override (default: localhost)
OPENLINEAR_GITHUB_CALLBACK_PORT	No	Callback port override (default: 0 — random available port)
OPENLINEAR_GITHUB_CALLBACK_PATH	No	Callback path override (default: /callback)

Browser Flow Setup

To use the browser OAuth flow, you need a GitHub OAuth app:

1. Create a GitHub OAuth App

   Go to GitHub Developer Settings and create a new OAuth App.

2. Configure callback URL

   Set the authorization callback URL to http://localhost/callback (loopback).

3. Set the client secret

   export OPENLINEAR_GITHUB_CLIENT_SECRET=your-client-secret
   
4. Login

   openlinear github login --browser
   

---

Token Storage

Tokens are stored locally at:

~/.config/openlinear/github-auth.json

This file contains only the OAuth access token. No passwords or client secrets are stored.

---

Desktop App Integration

The desktop app also supports GitHub authentication through its UI:

1. Local GitHub CLI — The sidecar API checks for an existing gh auth token
2. Browser OAuth — The desktop app can initiate OAuth via the sidecar API
3. Device Flow — Available as a fallback from the Settings page

The desktop app stores tokens in the same location as the CLI, so authentication is shared between both.