Skip to content

feat: support GitHub App authentication as alternative to PAT #31

Description

@rhoades-brown

Is your feature request related to a problem? Please describe.
Currently the plugin only supports Personal Access Tokens (PATs) for GitHub authentication. PATs are long-lived, have broad scope, and must be manually rotated. For users who want tighter security controls — especially those syncing private vaults or working within organisations — PATs are not ideal. GitHub Apps provide fine-grained, time-limited, repository-scoped tokens that are the recommended approach for programmatic access.

Describe the solution you'd like
Add GitHub App as an alternative authentication method alongside the existing PAT flow. The user would:

  1. Create a GitHub App (or use one provided by their org) and install it on the target repositories.
  2. In the plugin settings, choose "GitHub App" as the auth method instead of "Personal access token".
  3. Provide the App ID, Private Key (PEM), and Installation ID.
  4. The plugin generates short-lived installation tokens automatically, refreshing them before they expire (tokens last 1 hour).

Implementation plan

Settings types (src/types/settings.ts)

  • Add authMethod: 'pat' | 'github-app' to AuthConfig
  • Add appId, privateKey, installationId fields
  • Update DEFAULT_SETTINGS (default to 'pat' for backwards compatibility)

New dependency

  • Add @octokit/auth-app for the GitHub App auth strategy
  • Verify it bundles correctly with esbuild in a browser environment (may need Web Crypto API fallback if jsonwebtoken doesn't work in Obsidian's runtime)

GitHubService (src/services/githubService.ts)

  • Add authenticateAsApp(appId, privateKey, installationId) method using createAppAuth strategy
  • Handle automatic installation token refresh (1-hour expiry)
  • Adapt user identity — GitHub Apps act as a bot, so use the App's bot name instead of getAuthenticated() user

Plugin lifecycle (main.ts)

  • Branch validateAndConnect() on authMethod
  • Store private key in SecretStorage (same pattern as PAT migration)
  • Ensure startup auto-connect works for both methods

Settings UI (src/ui/settingsTab.ts)

  • Add auth method dropdown (PAT vs GitHub App) in the authentication section
  • Conditionally show PAT fields or App ID / Private Key / Installation ID fields
  • Update connection status display for bot identity
  • Add help text explaining how to create a GitHub App

Additional repos

  • Add installationId to AdditionalRepoConfig for repos under different installations
  • Handle the case where useMainToken is true but the main App installation doesn't cover the additional repo

Tests

  • Update GitHubService tests for the new auth path
  • Test token refresh logic
  • Test settings migration (existing PAT configs must load without changes)

Describe alternatives you've considered

  • Fine-grained PATs: GitHub now offers fine-grained PATs with repo-level scoping and expiry, which address some of the same concerns. However, they still require manual rotation and don't support automatic token refresh.
  • OAuth App flow: Would require a server-side component to handle the OAuth callback, which conflicts with the plugin's offline-first design.
  • GitHub CLI auth delegation: Using gh auth token to inherit CLI credentials. This only works on desktop and adds an external dependency.

Additional context

  • The octokit package (already a dependency at v5.0.5) supports GitHub App auth via @octokit/auth-app
  • GitHub App installations are scoped per-repo (or per-org), which aligns well with the plugin's multi-repo architecture
  • Risk: @octokit/auth-app uses JWT signing internally — need to verify this works in Obsidian's Electron/browser runtime without Node.js-only crypto modules
  • This would be a minor version bump (0.9.0) since it's additive and fully backwards-compatible

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions