Authentication - GitHub Desktop

Overview

GitHub Desktop provides secure authentication for various Git hosting services, including GitHub.com, GitHub Enterprise Server, and generic Git servers. Authentication enables cloning private repositories, pushing changes, and creating pull requests.

OAuth for GitHub

Secure OAuth 2.0 authentication for GitHub services

Personal Access Tokens

Token-based authentication for Git operations

SSH Support

Use SSH keys for authentication

Credential Storage

Secure storage using OS credential managers

GitHub Authentication

GitHub Desktop uses OAuth 2.0 for authenticating with GitHub:

Initiate Sign-In

Click File > Options > Accounts > Sign in (GitHub.com or Enterprise)

Browser Opens

Your default browser opens to GitHub’s authorization page

Authorize Application

Review permissions and click Authorize desktop

Return to Desktop

Browser redirects back to GitHub Desktop with a token

Complete

You’re signed in and can access your repositories

OAuth Scopes

GitHub Desktop requests these OAuth scopes:

repo: Full control of private repositories
- Read and write repository data
- Create pull requests
- Access commit status
read:org: Read organization membership
- List organization repositories
- View organization membership
user:email: Access user email addresses
- Get commit email address
- Match commits to user
workflow: Update GitHub Actions workflows
- Modify workflow files
- Trigger workflow runs

OAuth tokens are stored securely in your operating system’s credential manager (Credential Manager on Windows, Keychain on macOS, libsecret on Linux).

Authentication Key Storage

From the source code:

// From app/src/lib/auth.ts
export function getKeyForAccount(account: Account): string {
  return getKeyForEndpoint(account.endpoint)
}

export function getKeyForEndpoint(endpoint: string): string {
  const appName = __DEV__ ? 'GitHub Desktop Dev' : 'GitHub'
  return `${appName} - ${endpoint}`
}

Tokens are stored with keys like:

GitHub - https://api.github.com
GitHub - https://github.example.com/api/v3

This allows multiple accounts (GitHub.com and Enterprise) simultaneously.

GitHub Enterprise Authentication

Adding Enterprise Server

Open Accounts

File > Options > Accounts

Click Sign in next to “GitHub Enterprise Server”

Enter Server URL

Enter your Enterprise server address:

https://github.company.com

Authenticate

Complete OAuth flow on your Enterprise server

Enterprise Requirements

GitHub Enterprise Server 2.15 or later
OAuth application must be registered
Network access to the server
Valid SSL certificate (or exception configured)

Multiple Enterprise Servers

You can connect to multiple Enterprise servers:

Each server requires separate sign-in
Separate OAuth tokens for each
Switch between servers when cloning/creating PRs

Generic Git Authentication

For non-GitHub Git servers (GitLab, Bitbucket, self-hosted, etc.):

Username and Password

GitHub Desktop can store credentials for generic Git servers:

// From app/src/lib/generic-git-auth.ts
export const genericGitAuthUsernameKeyPrefix = 'genericGitAuth/username/'

function getKeyForUsername(endpoint: string): string {
  return `${genericGitAuthUsernameKeyPrefix}${endpoint}`
}

export function getGenericUsername(endpoint: string): string | null {
  const key = getKeyForUsername(endpoint)
  return localStorage.getItem(key)
}

export function setGenericPassword(
  endpoint: string,
  username: string,
  password: string
): Promise<void> {
  const key = getKeyForEndpoint(endpoint)
  return TokenStore.setItem(key, username, password)
}

export function setGenericCredential(
  endpoint: string,
  username: string,
  password: string
) {
  setGenericUsername(endpoint, username)
  return setGenericPassword(endpoint, username, password)
}

When Credentials Are Requested

GitHub Desktop prompts for credentials when:

Cloning a repository from a non-GitHub URL
Pushing to a remote that requires authentication
Fetching from a private repository

Credential Prompt:

Username field
Password/token field
“Remember credentials” checkbox

For generic Git servers, use a personal access token instead of your password for better security.

Personal Access Tokens

Creating GitHub Tokens

Open GitHub Settings

Go to GitHub.com > Settings > Developer settings > Personal access tokens > Tokens (classic)

Generate New Token

Click Generate new token (classic)

Set Scopes

Select scopes:

✓ repo (full control of private repositories)
✓ workflow (update workflows)
✓ read:org (read org membership)

Generate

Click Generate token and copy the token immediately

Use in Desktop

Personal access tokens grant access to your account. Keep them secret and never commit them to repositories.

Token Expiration

GitHub tokens can expire:

GitHub recommends setting expiration dates
GitHub Desktop will prompt for re-authentication when token expires
Sign in again to refresh the token

SSH Authentication

Using SSH Keys

GitHub Desktop supports SSH authentication:

Generate SSH Key

ssh-keygen -t ed25519 -C "your_email@example.com"

Add to SSH Agent

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Add to GitHub

Copy public key:

cat ~/.ssh/id_ed25519.pub

Add to GitHub: Settings > SSH and GPG keys > New SSH key

Use SSH URLs

Clone repositories using SSH URLs:

git@github.com:user/repo.git

SSH vs HTTPS

HTTPS (Recommended)
SSH

Pros:

Works through most firewalls
No SSH key setup required
Easier for beginners
GitHub Desktop handles tokens automatically

Cons:

Requires token or OAuth
Some corporate proxies may inspect traffic

URL Format:

https://github.com/user/repo.git

Pros:

More secure (key-based)
No password prompts
Works well for automation
Can use SSH config for custom settings

Cons:

Often blocked by corporate firewalls
Requires SSH key setup
Doesn’t work through HTTP proxies

URL Format:

git@github.com:user/repo.git

GitHub Desktop works with both HTTPS and SSH remotes. However, OAuth authentication only applies to HTTPS. SSH uses your SSH keys managed by ssh-agent.

Credential Storage

Operating System Integration

GitHub Desktop uses the OS credential manager:

Windows
macOS
Linux

Windows Credential ManagerCredentials stored in:

Control Panel > Credential Manager
Windows Credentials > Generic Credentials

Entries named:

GitHub - https://api.github.com
genericGitAuth/username/https://gitlab.com

View/Edit:

Open Credential Manager
Find GitHub Desktop entries
Edit or remove as needed

macOS KeychainCredentials stored in:

Keychain Access app
Login keychain

Entries named:

GitHub - https://api.github.com

View/Edit:

Open Keychain Access
Search for “GitHub”
Double-click to view or delete

Token Lifetime

Tokens are stored until:

You sign out of GitHub Desktop
You manually remove from credential manager
Token expires (GitHub tokens)
Revoked on GitHub.com/Enterprise

Two-Factor Authentication (2FA)

GitHub 2FA Support

GitHub Desktop fully supports 2FA:

Start the OAuth sign-in process

Enter Password

Enter your GitHub password

2FA Prompt

Enter your 2FA code:

Authenticator app code
SMS code
Security key

Authorize

Complete authorization

Once authorized with OAuth, you don’t need to enter 2FA codes for each Git operation. The OAuth token handles authentication.

2FA with HTTPS Git

If using HTTPS without OAuth:

Password authentication is disabled for 2FA accounts
Must use a personal access token instead
Create token on GitHub.com > Settings > Developer settings
Use token as password when prompted

Authentication Troubleshooting

If OAuth authentication doesn’t work:Check:

Browser opens to GitHub?
Firewalls blocking redirect?
Correct server URL for Enterprise?
Try signing out and back in

Fix:

# Clear stored credentials
# Windows: Credential Manager
# macOS: Keychain Access  
# Linux: Seahorse/KWalletManager

Authentication Fails After Working

If authentication stops working:Reasons:

Token expired
Token revoked on GitHub
Password changed
2FA enabled/disabled

Fix:

Sign out of GitHub Desktop
Sign back in
Re-authorize OAuth

SSH Key Not Working

If SSH authentication fails:Check:

# Test SSH connection
ssh -T git@github.com

# Verify key is added
ssh-add -l

# Check SSH config
cat ~/.ssh/config

Common Issues:

SSH key not added to ssh-agent
Public key not added to GitHub
Wrong permissions on ~/.ssh directory
Firewall blocking port 22

Generic Git Credentials Not Saved

If credentials aren’t remembered:Check:

“Remember credentials” was checked
Credential manager is accessible
Permissions on credential storage

Manual Storage:

# Configure Git credential helper
git config --global credential.helper manager  # Windows
git config --global credential.helper osxkeychain  # macOS  
git config --global credential.helper libsecret  # Linux

Enterprise Server Not Accessible

If Enterprise server sign-in fails:Verify:

Correct server URL
Server is reachable from your network
SSL certificate is valid
OAuth app is configured on server
You have an account on the server

Test:

curl https://github.company.com/api/v3

Signing Out

Remove Account

Open Accounts

File > Options > Accounts

Sign Out

Click Sign out next to the account

Confirm

Confirm you want to sign out

Token Removed

OAuth token is deleted from credential manager

What Happens

When you sign out:

OAuth token is removed
Can no longer clone private repos
Can’t push to repositories
Can’t create pull requests
Local repositories remain intact

Removing Credentials

// From app/src/lib/generic-git-auth.ts
export function deleteGenericCredential(endpoint: string, username: string) {
  localStorage.removeItem(getKeyForUsername(endpoint))
  return TokenStore.deleteItem(getKeyForEndpoint(endpoint), username)
}

Generic Git credentials can be removed:

Sign out from Accounts settings
Manually delete from OS credential manager
Clear browser data (for OAuth state)

Best Practices

Use OAuth for GitHub: OAuth is more secure than personal access tokens and provides a better user experience with automatic token refresh.

Keep Tokens Secret
- Never commit tokens to repositories
- Don’t share tokens with others
- Regenerate if exposed
Use HTTPS in Corporate Networks
- HTTPS works through most proxies
- SSH often blocked by firewalls
- Easier to troubleshoot
Enable 2FA
- Adds extra security layer
- Required for many organizations
- Works seamlessly with OAuth
Review Token Scopes
- Only grant necessary permissions
- Audit tokens periodically
- Revoke unused tokens
Separate Work and Personal
- Use different accounts for work/personal
- Sign in to appropriate account per repository
- Consider separate Git email configs

Security Considerations

Token Security

Storage: Tokens encrypted by OS credential manager
Transmission: Always sent over HTTPS
Scope: Limited to requested permissions
Rotation: Can be revoked and regenerated

SSH Key Security

Private Key: Keep private, never share
Passphrase: Use strong passphrase on private key
Agent: Use ssh-agent to avoid repeated passphrase entry
Key Type: Use Ed25519 or RSA 4096-bit keys

Revoking Access

Revoke GitHub Desktop access:

Go to GitHub.com > Settings > Applications
Find “GitHub Desktop” under Authorized OAuth Apps
Click Revoke

This invalidates all tokens for GitHub Desktop.

​Overview

OAuth for GitHub

Personal Access Tokens

SSH Support

Credential Storage

​GitHub Authentication

​OAuth Sign-In

​OAuth Scopes

​Authentication Key Storage

​GitHub Enterprise Authentication

​Adding Enterprise Server

​Enterprise Requirements

​Multiple Enterprise Servers

​Generic Git Authentication

​Username and Password

​When Credentials Are Requested

​Personal Access Tokens

​Creating GitHub Tokens

​Token Expiration

​SSH Authentication

​Using SSH Keys

​SSH vs HTTPS

​Credential Storage

​Operating System Integration

​Token Lifetime

​Two-Factor Authentication (2FA)

​GitHub 2FA Support

​2FA with HTTPS Git

​Authentication Troubleshooting

​Signing Out

​Remove Account

​What Happens

​Removing Credentials

​Best Practices

​Security Considerations

​Token Security

​SSH Key Security

​Revoking Access

​Related Topics

Overview

GitHub Authentication

OAuth Sign-In

OAuth Scopes

Authentication Key Storage

GitHub Enterprise Authentication

Adding Enterprise Server

Enterprise Requirements

Multiple Enterprise Servers

Generic Git Authentication

Username and Password

When Credentials Are Requested

Personal Access Tokens

Creating GitHub Tokens

Token Expiration

SSH Authentication

Using SSH Keys

SSH vs HTTPS

Credential Storage

Operating System Integration

Token Lifetime

Two-Factor Authentication (2FA)

GitHub 2FA Support

2FA with HTTPS Git

Authentication Troubleshooting

Signing Out

Remove Account

What Happens

Removing Credentials

Best Practices

Security Considerations

Token Security

SSH Key Security

Revoking Access

Related Topics