Auth and config

Active contributors: William Martin, Mislav, vilmibm

Purpose

gh auth manages OAuth tokens, host configurations, and git credential helpers. gh config reads and writes user-level configuration. Together they own everything in ~/.config/gh/ plus the OS keyring entries.

Directory layout

pkg/cmd/auth/
  auth.go              # NewCmdAuth: registers subcommands
  login/               # OAuth device flow + token paste
  logout/              # Revokes session, clears keyring entry
  status/              # Lists hosts, accounts, scopes, token sources
  switch/              # Switch the active account on a host
  refresh/             # Re-authorize with new scopes
  setupgit/            # Configure git credential helper
  gitcredential/       # Internal git credential helper hook
  token/               # Print the active token
  shared/              # OAuth flow, scope tables, host prompting

pkg/cmd/config/
  config/              # subcommand registration
  get/  set/  list/  clear-cache/

internal/config/
  config.go             # ~25 KB; central config loader and migrator
  migration/            # v1 -> v2 multi-account migration
  stub.go               # in-memory config used in tests

internal/authflow/      # OAuth device-flow plumbing
internal/keyring/       # OS keyring wrapper around go-keyring

Key abstractions

Symbol	File	Role
NewCmdAuth	pkg/cmd/auth/auth.go	Subcommand registration.
loginRun	pkg/cmd/auth/login/login.go	Drives device flow or token paste, hosts prompt, scope confirmation.
statusRun	pkg/cmd/auth/status/status.go	Lists hosts, account, scopes, token storage, git protocol.
switchRun	pkg/cmd/auth/switch/switch.go	Multi-account switching (introduced with the v2 config migration).
Config	internal/config/config.go	The 25 KB on-disk config loader, with migration hooks.
Authentication	internal/config/config.go	Returns the current host, token, and active user. Used by every command that talks to the API.
Migration	internal/config/migration/	Upgrades pre-v2 configs to multi-account form.
oauth.Flow	internal/authflow/	OAuth device flow client.
keyring	internal/keyring/	Stores tokens in the OS secret store when available.

How it works

gh auth login flow on a TTY:

graph TD
    A[gh auth login] --> B[Prompt for host]
    B --> C[Prompt for protocol https/ssh]
    C --> D[Prompt for token type web/paste]
    D -->|web| E[OAuth device flow]
    D -->|paste| F[Prompt for token]
    E --> G[Validate via api]
    F --> G
    G --> H[Persist host + user in hosts.yml]
    G --> I[Persist token in keyring or hosts.yml]
    G --> J[Optionally configure git credential helper]

status and switch are mostly UI on top of internal/config. The migrator runs lazily: when Config.Authentication() finds a v1 layout it returns an upgraded copy and writes it back.

Integration points

• Every API client call uses Config.Authentication().DefaultHost() to choose a host and Config.Authentication().Token() (or its keyring-backed sibling) to authenticate.
• gh auth setup-git configures git's credential helper to call gh auth git-credential, which is the hidden subcommand that bridges git's helper protocol to the CLI's stored token.
• gh config get/set use the same loader, which is why the on-disk format stays consistent between manual edits and CLI operations.
• Multi-account behaviour is what gives multiple hosts and multiple accounts per host coherent semantics. See docs/multiple-accounts.md.

Entry points for modification

• Adding a config key: extend internal/config/config.go (the keys + accessors live here) and surface it via gh config.
• New scope: update the scope table in pkg/cmd/auth/shared/oauth_scopes.go and the OAuth client ID list.
• New auth source (e.g. environment variable): the precedence order lives in internal/config/config.go (Authentication.Token); add the new source there.

Key source files

File	Purpose
pkg/cmd/auth/login/login.go	Login flow.
pkg/cmd/auth/status/status.go	Status output.
pkg/cmd/auth/refresh/refresh.go	Re-auth with new scopes.
pkg/cmd/auth/setupgit/setupgit.go	Git credential helper installer.
pkg/cmd/auth/gitcredential/gitcredential.go	The git credential protocol bridge.
pkg/cmd/config/get/get.go and set/set.go	Read/write config.
internal/config/config.go	The on-disk config representation.
internal/config/migration/migration.go	v1 -> v2 migration.
internal/authflow/flow.go	Device flow implementation.

Related pages

• Config and auth (system-level).
• API client for how the token reaches outgoing requests.
• Patterns and conventions.