How to Configure YubiKey with GitHub

#github #security

If you're anything like me, you’ve probably typed in authenticator codes a hundred times a day, just to push code, review a PR, merge something trivial or log in to another organization (I am part of like 7-8 of them).
It's secure, sure, but also kind of exhausting.

That's why I switched to a YubiKey (or at least one of the reason).

YubiKey is a small physical device that lets you log in securely with a single touch — no need to pull out your phone, open the app, copy a 6-digit code, and race against the clock. Since I started using it with GitHub, authentication has been both faster and safer (but I care more about the speed here, for my mental health 😃)

Prerequisites

Before we get started, make sure you have everything you need:

🔐 A YubiKey

Any model that supports FIDO2/WebAuthn will work. Popular ones include:
- YubiKey 5 Series
- Security Key by Yubico
🌐 A compatible browser

You’ll need a browser that supports security keys, such as:
- Google Chrome
- Mozilla Firefox
- Microsoft Edge

💡 Tip: If you have multiple YubiKeys (e.g., one for backup), you can register them later — GitHub supports more than one.

Step 1: Enable Two-Factor Authentication on GitHub

Before you can add a YubiKey, GitHub requires that you enable two-factor authentication (2FA). If you’ve already done this, feel free to skip to the next section.

🛠 How to enable 2FA:

Go to your GitHub Settings.
In the left sidebar, click “Passwords and authentication.”
Under “Two-factor authentication”, click “Enable two-factor authentication.”
GitHub will guide you through setting up a primary 2FA method:
- Choose “Authenticator app”
- Scan the QR code with your app (e.g., Microsoft Authenticator, Google Authenticator)
- Enter the 6-digit code to confirm
Save your recovery codes somewhere secure — this is important if you lose access to your 2FA device.

Once that’s done, you’re ready to pair your YubiKey.

Step 2: Add YubiKey as a Security Key

With 2FA enabled, you can now register your YubiKey with GitHub. This allows you to log in with a tap — no code-copying, no app-switching.

🔐 Add your YubiKey:

Go to your GitHub Settings > Passwords and authentication.
Scroll down to the "Security keys" section.
Click “Register new security key.”
Insert your YubiKey into a USB port.
Tap the gold disk (or side button, depending on your model) when prompted by your browser.
Give your key a recognizable name (e.g., YubiKey-Work, YubiKey-Home).
Click “Register” to complete the setup.