GitHub Doctor is a command-line tool designed to simplify SSH key management for GitHub accounts. It automates the creation of SSH keys, configures your SSH agent, and optionally uploads the generated public key to your GitHub account.
Key Features:
Automatic Key Generation: Creates new SSH keys when needed or verifies existing ones.
SSH Agent Configuration: Adds keys to the SSH agent and ensures proper configuration for use with GitHub.
OAuth Integration: Uses a secure OAuth token to upload keys to your account without persisting sensitive information.
Idempotency: Commands can be safely re-run, making it ideal for scripting and automated setups.
Audience & Benefit:
Ideal for developers, DevOps engineers, and anyone setting up SSH access on a new machine or troubleshooting SSH configurations. GitHub Doctor streamlines the setup process, reducing errors and saving time while ensuring secure access to your repositories.
Install GitHub Doctor via winget on Windows with winget install --id=tekumara.gh-doctor -e.
README
GitHub Doctor
GitHub Doctor creates an SSH key and config and optionally uploads the key to your account. It can also rotate existing keys.
Commands are idempotent and can be re-run, making GitHub Doctor easy to use in scripts and useful for repairing misconfigurations.
❯ gh-doctor ssh -d
ℹ Removing existing identities from SSH agent.
Please complete authentication in your browser...
https://github.com/login/oauth/authorize?client_id=Ov23liukLtggLaIpvb2o&code_challenge=O3YS8ZSA2_mZDPie&code_challenge_method=S256&redirect_uri=http%3A%2F%2F127.0.0.1%3A55254&response_type=code&scope=admin%3Apublic_key&state=4WAZT_6psyuBE
✓ Authenticated to github.com as tekumara using token
Creating key file /Users/tekumara/.ssh/github.com
Please specify a passphrase!
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Generating public/private ed25519 key pair.
Your identification has been saved in /Users/tekumara/.ssh/github.com
Your public key has been saved in /Users/tekumara/.ssh/github.com.pub
The key fingerprint is:
SHA256:F9pcXNW/NPP4tSATn2hxuPVr5Tx5LjrWKiCU86XugK8 github.com (beebop)
The key's randomart image is:
+--[ED25519 256]--+
| ..o|
| . . .|
| . . + .|
| + +.* o +.|
| . oSo+ O +.=|
| .. +. * +.o+|
| . .o .. o..+*|
| . .. . o o*=|
| E.... oo+.o+|
+----[SHA256]-----+
✓ Key github.com (beebop) uploaded
✓ Added Host github.com to ~/.ssh/config
ℹ Server accepts key: /Users/tekumara/.ssh/github.com ED25519 SHA256:F9pcXNW/NPP4tSATn2hxuPVr5Tx5LjrWKiCU86XugK8 explicit
✓ Authenticated to github.com as tekumara using ssh
Run again to verify the SSH key. Because the key exists it will be verified rather than creating a new key. To rotate an existing key use the -r flag.
Help
❯ gh-doctor ssh --help
Ensure ssh works.
Verify ssh and if needed:
* Fetch a token using the gh-doctor OAuth app with scope to create SSH keys.
This token is used once and not stored anywhere.
* Create a private ssh key file.
* Add the GitHub host to ~/.ssh/config.
* Upload the ssh key to your GitHub user account (manually or using an OAuth app).
Example entry added to ~/.ssh/config:
Host github.com
AddKeysToAgent yes
UseKeychain yes # (macOS only)
IdentityFile ~/.ssh/github.com
During verification any SSH agent identities are removed in case incorrect keys were loaded.
Usage:
gh-doctor ssh [flags]
Flags:
-d, --doctoken Use the GitHub Doctor OAuth app to upload the key
-g, --ghtoken Use GH_TOKEN env var then GitHub CLI OAuth app to upload the key
-h, --hostname string GitHub hostname (default "github.com")
-k, --keyfile string Private key file (default "~/.ssh/[hostname]")
-r, --rotate Rotate existing key (if any)
-s, --sso Prompt to authorise the key for organisations using SAML SSO
Global Flags:
--help Show help for command
Uploading the key
Manual upload
By default gh-doctor will prompt you to manually upload the key. This does not require gh-doctor to authenticate to GitHub using a token. It is guaranteed to create SSH keys that work for github.com, Github Enterprise Server (GHES) hosts, and any organisation.
OAuth app (-d)
This uses the gh-doctor OAuth app to obtain an OAuth token with the admin:public_key scope. This token is used to upload the SSH key.
Because of this, the gh-doctor OAuth app is most useful for github.com personal repos.
GitHub CLI app (-g)
This will use any token in the GH_TOKEN environment variable, falling back to obtaining one from the GitHub's official cli tool (which must be installed separately). This token is used to upload the SSH key and must have the admin:public_key scope.
Unlike the gh-doctor OAuth app, this works by default for GHES and organisation resources because the GitHub CLI is considered an internal OAuth app and does not require approval for use.
NB: GitHub can only generate long-lived OAuth tokens. The GitHub CLI persists these in the keychain, but gh auth token will return the token in plaintext bypassing any keychain security. It is therefore less secure that using a gh-doctor OAuth app token which is never stored. However, this is moot if you are already using the GitHub CLI.
Organisations that use SAML single sign-on
If your organisation uses SAML single sign-on authorise your SSH key for use with the organisation.
Troubleshooting
I can authenticate but can't pull or push an organisation repo
gh doesn't modify your ssh config, or load the key into the ssh agent as per the GitHub docs.
gh doesn't diagnose and fix misconfigurations. Nor does it run idempotently.
gh-doctor tokens are never persisted. GitHub can only generate long-lived OAuth tokens which don't expire. gh persists these tokens in the keychain, but gh auth token will return the token in plaintext bypassing any keychain security. gh-doctor tokens are only used once in-memory.