Add an SSH Key to GitHub with gh ssh-key add

Upload the wrong file to gh ssh-key add and GitHub happily accepts a key you never meant to register. You will add one existing public SSH key to your GitHub account with gh ssh-key add, then confirm that GitHub has it. Allow about ten minutes if the key already exists. This guide uses GitHub CLI 2.87.3, installed from the gh package on this machine.

Warning: the command changes your GitHub account, so pause at the key-selection checkpoint. You need an authenticated gh session, a public key file such as ~/.ssh/id_ed25519.pub, and permission to add keys to the account. No elevated privileges are needed, and do not use sudo: it can make you inspect a different user's SSH directory and upload the wrong key.

1. Check the CLI and authentication

Confirm the installed command and the account it will use:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth status

The second command should report an authenticated account and host. If it says you are not logged in, stop here and run the normal gh auth login flow for the account you intend to change. Authentication is a prerequisite, not something gh ssh-key add silently fixes.

Checkpoint: write down the GitHub account and host shown by gh auth status. If this is an enterprise host, make sure it is the host you expect before continuing.

2. Inspect the public key before uploading it

List likely public keys without exposing private key material:

$ find "$HOME/.ssh" -maxdepth 1 -type f -name '*.pub' -print
/home/you/.ssh/id_ed25519.pub
$ ssh-keygen -lf "$HOME/.ssh/id_ed25519.pub"
256 SHA256:REPLACE_WITH_THE_FINGERPRINT [email protected] (ED25519)

Replace the path with the key you actually want to use. The fingerprint is a useful identity check, especially when several keys have similar names. A file ending in .pub is the public half; never pass a private key such as ~/.ssh/id_ed25519 to this command. If the public file is missing but the private key is yours, derive a new public file without uploading anything:

$ ssh-keygen -y -f "$HOME/.ssh/id_ed25519" > /tmp/id_ed25519.pub
$ ssh-keygen -lf /tmp/id_ed25519.pub

Check the fingerprint, then use that temporary public file or move it into your SSH directory with the right ownership and permissions. The private key stays on this machine.

3. Add the key as an authentication key

Give the key a meaningful title. It helps you recognise the device later; it is not the SSH key itself:

$ gh ssh-key add "$HOME/.ssh/id_ed25519.pub" \
    --title "workstation-2026-09" \
    --type authentication
✓ SSH key added to your account.

The positional argument is the key file. --title sets the new key's title. The default type is authentication, so the explicit option above is mainly a review aid: keep it when copying the command into a script or runbook.

For a key meant to sign commits rather than authenticate SSH connections, use the other supported type:

$ gh ssh-key add "$HOME/.ssh/id_ed25519.pub" \
    --title "signing-key-2026-09" \
    --type signing

Do not pick signing just because the key has a familiar name. Decide what the key is for first: --type accepts only authentication or signing.

4. Verify the account record

List the account's SSH keys and look for the title and fingerprint you just checked:

$ gh ssh-key list
TITLE                 TYPE            CREATED
workstation-2026-09   authentication  2026-09-24T12:34:56Z

Exact columns and timestamp will reflect your account. The important check is that the expected title, type and key fingerprint appear in the list; a successful add message alone is not proof you changed the intended account.

If your actual aim is to use the key for Git operations, run a separate connection check after reviewing the account record:

$ ssh -T [email protected]
Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

GitHub may phrase this response differently, and a signing-only key is not a replacement for an authentication key. For an enterprise host, use that host's SSH endpoint and the host shown by your gh configuration.

5. Recover from a wrong or duplicate key

Recovery: adding a key is a remote account change. If you selected the wrong public file, do not delete files from ~/.ssh as a first response: that could remove the only private key you can use. First identify the unwanted entry with gh ssh-key list, including its numeric ID if shown, then use the matching delete command:

$ gh ssh-key delete KEY_ID
? Are you sure you want to delete this SSH key? Yes
✓ SSH key deleted from your account.

Deletion is irreversible from the command line. Treat the confirmation as a destructive checkpoint, and do not use a guessed ID. If you are unsure, stop after listing the keys and compare fingerprints in the GitHub account settings before deleting anything.

Done means