Codumentor logo Codumentor

GitHub OAuth Plugin

Registers GitHub as a connectable provider for the OAuth
plugin, so users can link their GitHub account from **Settings → Extensions →
OAuth Accounts**. The plugin owns no storage and runs no flow of its own: it
declares GitHub's endpoints and default scopes, and the OAuth plugin does the
connecting, encrypting and refreshing.

GitHub uses the device-code flow — the user opens a URL and types the code
Codumentor shows — so there is no callback URL to register and no client secret
to keep.

Configuration

Load this plugin and the OAuth plugin. This plugin's priority
must be lower than OAuth's (3 vs 4): the OAuth plugin emits
onRegisterOAuthProviders from inside its own register(), so a provider whose
handler is not in place yet is never asked to register.

plugins:
  - module: codumentor.plugins.oauth
    class: OAuthPlugin
    priority: 4
    args:
      enabled: true

  - module: codumentor.plugins.github_oauth
    class: GitHubOAuthPlugin
    priority: 3
    args:
      client_id: ${GITHUB_OAUTH_CLIENT_ID}

Parameters

ParameterTypeDefaultDescription
enabledbooltrueMaster on/off. When false the provider is not registered and GitHub does not appear in Settings.
client_idstring${GITHUB_OAUTH_CLIENT_ID}The OAuth app's client id. Falls back to the GITHUB_OAUTH_CLIENT_ID environment variable. Without it the provider is not registered and a warning names this parameter.
client_secretstring${GITHUB_OAUTH_CLIENT_SECRET}Only needed if you switch the app away from the device-code flow; the device-code flow has no secret.
default_scopeslist["read:user", "repo"]Scopes requested on first connect. Users can broaden the grant later from Settings without an operator change.

Create the OAuth app under **GitHub → Settings → Developer settings → OAuth
Apps and enable Device flow** on it. No callback URL is required.

Set auth.jwt_secret as well: the OAuth plugin keys its at-rest encryption off
that secret, and without it tokens cannot be stored securely (see
OAuth).

Using it

  1. Settings → Extensions → OAuth Accounts, pick GitHub, click Connect.
  2. Open the URL GitHub shows and enter the device code.
  3. Grants are per (user, provider, account) — two people in the same instance never share a connection — and refresh happens automatically before expiry.

Connecting requires the oauth:manage permission, which the built-in
power_user and admin roles have.

See also