Overview
GitHub Desktop uses OAuth web application flow to interact with the GitHub API and perform actions on behalf of users. The application is bundled with OAuth credentials (Client ID and Secret) for authentication.Developer OAuth Application
Default Credentials
For external contributors and development builds, GitHub Desktop includes a developer OAuth application to enable local testing without configuration. Fromapp/app-info.ts:5:
Limitations
The developer OAuth application will not work with GitHub Enterprise. Sign-in will fail on the OAuth callback due to missing credentials.
Custom OAuth Credentials
Environment Variables
To use your own OAuth application, set these environment variables before building:Build-Time Injection
OAuth credentials are bundled into the application during the webpack build process. The environment variables are read and replaced in the source code at build time.Create GitHub OAuth App
Register a new OAuth application at GitHub Developer Settings.
Set environment variables
Export
DESKTOP_OAUTH_CLIENT_ID and DESKTOP_OAUTH_CLIENT_SECRET in your shell.Authentication Flow
OAuth Web Application Flow
GitHub Desktop implements the standard OAuth 2.0 authorization code flow:Authorization Request
The desktop application initiates OAuth by redirecting to GitHub’s authorization endpoint:Token Exchange
After user approval, GitHub redirects back with an authorization code. Desktop exchanges this for an access token:Credential Storage
Keychain Integration
GitHub Desktop stores OAuth tokens securely using the operating system’s credential manager:- macOS: Keychain
- Windows: Credential Manager
- Linux: libsecret
Auth Key Generation
Fromapp/src/lib/auth.ts:4:
Development and production builds use different keychain keys to prevent conflicts when running both versions.
GitHub Enterprise Support
Production Credentials Required
To support GitHub Enterprise authentication:Multiple Accounts
Desktop supports multiple accounts across different endpoints:- GitHub.com accounts
- GitHub Enterprise Server accounts
- Multiple Enterprise instances
Security Considerations
Client Secret Protection
Best Practices
Required Scopes
GitHub Desktop requires these OAuth scopes:repo- Full control of private repositoriesuser- Read/write access to profile infoworkflow- Update GitHub Action workflows
Token Management
Token Refresh
GitHub OAuth tokens do not expire but can be revoked by:- User revoking access in GitHub settings
- OAuth app deletion
- Enterprise policy changes
Handling Revoked Tokens
When API requests fail with authentication errors:Development Workflow
Using Default Credentials
For local development and testing:Testing with Custom Credentials
Verifying Credentials
Check which credentials are bundled:Debugging Authentication
Common Issues
Sign-in fails with Enterprise- Verify custom OAuth credentials are set
- Check Enterprise instance URL is correct
- Ensure OAuth app is registered on Enterprise instance
- Check keychain/credential manager permissions
- Verify app has access to secure storage
- Test with different endpoint key
- Ensure OAuth app callback URL matches Desktop’s expected URL
- Check for HTTPS requirement
Enable Debug Logging
API Integration
Using OAuth Token
Once authenticated, the token is included in all GitHub API requests:Rate Limiting
Authenticated requests have higher rate limits:- Authenticated: 5,000 requests per hour
- Unauthenticated: 60 requests per hour
GitHub Enterprise instances may have different rate limits configured by administrators.