YubiKey for SSH and GitHub: The Technical Guide for Developers
Your private SSH key lives in a plain text file in ~/.ssh/. If someone accesses your laptop or infects it with malware, they can copy it in seconds. They don't need your password or your fingerprint.
A YubiKey changes that. The private key never leaves the hardware — not even you can export it. Without the physical key in the USB port or near NFC, no authentication is possible.
- An SSH key backed by FIDO2 hardware
- Signing Git commits with that same key
- YubiKey as a security key on GitHub (2FA)
Why the threat model changes
A normal SSH key is a file. It can be copied, leaked in a misconfigured backup, or stolen by malware that reads the disk.
An SSH key backed by YubiKey (-sk, for "security key") is generated inside the FIDO2 chip. The system only stores a reference. Without the physical key connected, that reference is useless.
Plus, you can require touch verification on each use. Even if someone has remote access to your machine, they would need to physically touch the YubiKey to authenticate.
Generate an SSH key backed by YubiKey
You need OpenSSH 8.2 or later. It comes included on macOS and most modern Linux distributions. On Windows, use the integrated OpenSSH client or WSL.
Run ssh-keygen -t ed25519-sk -O resident -O verify-required -C "your-email@domain.com". The resident option stores the key on the YubiKey as well, not just on your disk.
The terminal will ask for the YubiKey PIN and then to touch the sensor. This generates the key pair inside the chip.
id_ed25519_sk.pub is generated in ~/.ssh/. That's the one you add to GitHub, GitLab, or your server's authorized_keys.
SSH as you normally would. The system will ask you to touch the YubiKey before authenticating.
With -O resident you can recover the key from the YubiKey itself on a new machine with ssh-keygen -K. You don't need to generate it from scratch again.
Sign your Git commits with the same key
Since Git 2.34 you can sign commits using an SSH key instead of GPG. It's the same YubiKey, without setting up a second signing system.
Run git config --global gpg.format ssh.
Run git config --global user.signingkey ~/.ssh/id_ed25519_sk.pub.
Run git config --global commit.gpgsign true. Each commit will ask you to touch the YubiKey.
In Settings → SSH and GPG keys → New SSH key, upload the same public key but as Signing Key type, not Authentication Key.
From here on, your commits appear as Verified on GitHub. Anyone can verify they came from your physical key, not just your username.
Enable YubiKey as 2FA on GitHub
Settings → Password and authentication → Security keys → Add.
Via USB or NFC, depending on the model. GitHub detects it as a WebAuthn/FIDO2 key.
Confirm registration. From now on, login will request the physical key, not a temporary code.
GitHub lets you add multiple keys as a 2FA method. Register a primary one and a backup from day one.
YubiKey models compatible with this workflow
| Model | Connector | SSH (FIDO2) | 2FA GitHub |
|---|---|---|---|
| YubiKey 5 NFC | USB-A + NFC | ✓ | ✓ |
| YubiKey 5C NFC | USB-C + NFC | ✓ | ✓ |
| Security Key NFC | USB-A + NFC | ✓ | ✓ |
| Security Key C NFC | USB-C + NFC | ✓ | ✓ |
All four models use the FIDO2 protocol to generate -sk keys, so the SSH and GitHub 2FA workflow works the same on all of them. The difference is in the physical port on your device.
How to organize your primary key and your backup
If you lose your only YubiKey, you lose access to SSH, your signed commits, and GitHub login. Always register a second key and keep it in a different place from the primary one.
2-Slot Card Holder
Carry your primary key and backup together in credit card format. Made in Spain (EU).
Keychain with Lanyard
For the key you use every day. NFC works without removing it from the case. Made in Spain (EU).
Frequently asked questions
Do I absolutely need two YubiKeys?
Not mandatory, but highly recommended. Without a backup key registered, a failure or loss leaves you without SSH access and GitHub account access until you use another recovery method.
Does it work the same on Windows, macOS, and Linux?
Yes, as long as you have OpenSSH 8.2 or later. macOS and recent Linux distributions include it by default. On Windows, use the system's OpenSSH client or WSL.
Can I use the same YubiKey for SSH and my Gmail?
Yes. A single YubiKey supports multiple FIDO2 credentials, one for each service where you register it — SSH, GitHub, Gmail, and other WebAuthn-compatible accounts.
What if I lose the YubiKey I used to sign commits?
Already-signed commits remain valid. To continue signing, register your backup key as a new Signing Key on GitHub and update user.signingkey in your Git configuration.
Is it worth migrating SSH and GitHub to YubiKey?
If you have SSH access to production servers or maintain repositories with collaborators, yes. Your private key stops being a copyable file and becomes dependent on physical hardware.
The real cost is not the key itself, but not having a backup organized. Solve that from day one.
As an Amazon Associate, I earn from qualifying purchases.
