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:
- Create a GitHub App (or use one provided by their org) and install it on the target repositories.
- In the plugin settings, choose "GitHub App" as the auth method instead of "Personal access token".
- Provide the App ID, Private Key (PEM), and Installation ID.
- 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
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:
Implementation plan
Settings types (
src/types/settings.ts)authMethod: 'pat' | 'github-app'toAuthConfigappId,privateKey,installationIdfieldsDEFAULT_SETTINGS(default to'pat'for backwards compatibility)New dependency
@octokit/auth-appfor the GitHub App auth strategyjsonwebtokendoesn't work in Obsidian's runtime)GitHubService (
src/services/githubService.ts)authenticateAsApp(appId, privateKey, installationId)method usingcreateAppAuthstrategygetAuthenticated()userPlugin lifecycle (
main.ts)validateAndConnect()onauthMethodSecretStorage(same pattern as PAT migration)Settings UI (
src/ui/settingsTab.ts)Additional repos
installationIdtoAdditionalRepoConfigfor repos under different installationsuseMainTokenis true but the main App installation doesn't cover the additional repoTests
GitHubServicetests for the new auth pathDescribe alternatives you've considered
gh auth tokento inherit CLI credentials. This only works on desktop and adds an external dependency.Additional context
octokitpackage (already a dependency at v5.0.5) supports GitHub App auth via@octokit/auth-app@octokit/auth-appuses JWT signing internally — need to verify this works in Obsidian's Electron/browser runtime without Node.js-only crypto modules