GitHub OAuth

The github-oauth lease backend creates GitHub App user access tokens with OAuth device flow. It is useful for local automation where you want GITHUB_TOKEN or GH_TOKEN to be short-lived and tied to the signed-in GitHub user, without storing a personal access token in fnox.toml.

Unlike github-app, this backend only needs the GitHub App client ID. It does not require an app private key or app client secret, so the config can be shared safely across a team.

Tokens are cached in the OS keyring by default and refreshed when GitHub returns a refresh token.

Configuration

[leases.github]
type = "github-oauth"
client_id = "Iv1.yourgithubappclientid"
scope = "repo read:org workflow"
duration = "8h"

Field	Required	Description
client_id	Yes	GitHub App client ID; no app secret or private key is required
scope	No	OAuth scopes to request (default: "repo read:org workflow")
env_var	No	Environment variable name for the token (default: "GITHUB_TOKEN")
keyring_service	No	OS keyring service for cached tokens (default: "fnox-github-oauth")
keyring_cache	No	Cache access/refresh tokens in the OS keyring (default: true)
open_browser	No	Try to open the device verification URL in a browser (default: true)
auth_base	No	OAuth token endpoint base URL (default: "https://github.com/login/oauth")
api_base	No	GitHub API base URL (default: "https://api.github.com")
duration	No	Requested duration; GitHub controls the actual token lifetime

Prerequisites

Create a GitHub App with device flow enabled and use its client ID. On first use, fnox prints a GitHub device verification URL and user code:

fnox exec -- gh pr list

Approve the device prompt in your browser. Subsequent runs reuse the cached token while it remains valid. In non-interactive mode (--non-interactive or FNOX_NON_INTERACTIVE), fnox fails instead of starting the device flow, so authorize once from an interactive terminal first.

Expiry and revocation

GitHub controls the returned token lifetime. Inspect the tracked lease rather than assuming the requested duration is enforced. This backend relies on expiry; revoking its fnox ledger entry does not provide immediate remote token revocation.

Credentials produced

Environment Variable	Description
GITHUB_TOKEN	GitHub user access token

The env var name is configurable via the env_var field.

Examples

GitHub CLI

[leases.github]
type = "github-oauth"
client_id = "Iv1.yourgithubappclientid"
env_var = "GH_TOKEN"

fnox exec -- gh pr checkout 123

Disable OS keyring cache

[leases.github]
type = "github-oauth"
client_id = "Iv1.yourgithubappclientid"
keyring_cache = false

With keyring caching disabled, fnox still caches active lease credentials in its lease ledger for the current project.

See also

• Credential Leases — overview and approaches
• GitHub App — installation access tokens for automation