BlogHow-to

How to set up GitHub 2FA with an authenticator app

9 min read

GitHub asks for a second factor after your password, and an authenticator app is the method GitHub itself recommends. Setting it up takes about five minutes: you scan a QR code in GitHub’s settings, type in one code to confirm, and save your recovery codes.

This guide walks through each step with the exact menu names GitHub uses, then covers the parts people search for afterwards: moving GitHub 2FA to a new phone, codes that are rejected, and getting back in when the phone is lost. Any authenticator app works; we use ours in the examples.

Before you start

You need your GitHub password, a phone with an authenticator app on it, and somewhere safe to keep a small text file of recovery codes. Any standard authenticator app works, including Google Authenticator, Microsoft Authenticator and U2 Secured Authenticator, because GitHub uses the open TOTP standard.

If GitHub emailed you to say 2FA is now required on your account, you have 45 days from that notice, then a 7-day grace period. After that, GitHub blocks access to the website until 2FA is on. GitHub selects accounts that contribute code, for example by publishing releases, packages or actions, or by owning an organisation.

How to set up GitHub 2FA with an authenticator app

Do this on a computer, so the QR code is on one screen and the phone is in your hand.

  • On GitHub, click your profile picture in the top-right corner, then Settings.
  • In the sidebar, under Access, click Password and authentication.
  • In the Two-factor authentication section, click Enable two-factor authentication. GitHub may ask for your password again.
  • On your phone, open your authenticator app and add an account. In U2 Secured Authenticator, tap + Add account, then Scan QR code.
  • Point the phone at the QR code under “Scan the QR code”. The app adds a GitHub entry showing a six-digit code. In U2 Secured, check the name and tap Save.
  • Back on GitHub, type the current code into the box under “Verify the code from the app”.
  • Under “Save your recovery codes”, click Download and store the file somewhere that is not your phone (see the next section).
  • Click I have saved my recovery codes. Two-factor authentication is now on.

Can’t scan the QR code? Click “setup key” under the QR code to see the secret as text. In U2 Secured, tap + Add account, then Enter manually, type GitHub as the issuer and paste the key. Leave the advanced settings as they are.

Save your GitHub recovery codes

GitHub gives you 16 recovery codes. Each one signs you in once, without your phone. They are the difference between losing your phone and losing your GitHub account, because GitHub Support will not turn 2FA off for you.

Keep the downloaded file, called github-recovery-codes.txt, in a password manager you can open from another device, or print it and keep the paper somewhere safe. Do not keep it only on the phone that runs your authenticator app, or the phone takes both with it.

You can see them again later: Settings, then Password and authentication, then View next to Recovery codes. If you think someone else has seen them, or you have used several, click Generate new recovery codes there. The old set stops working the moment you do.

The 28-day check-up

For 28 days after you turn on 2FA, GitHub watches for one successful sign-in with it. Sign out and back in once with a code from the app and the check-up is over. If you never do, GitHub asks you to use 2FA in an existing session on day 28, and gives you a shortcut to set it up again if your app is not working. It is there to catch setups that were never tested, so test yours on day one.

Add a backup method

Once the authenticator app is set up, GitHub lets you add more methods, and adding one is the best protection against being locked out.

  • A passkey or a security key. Passkeys and security keys are phishing-resistant, because the browser checks that it is really github.com before the key answers. A passkey can also sign you in without your password.
  • GitHub Mobile, which approves sign-ins with a tap.
  • Text message (SMS), only in the countries GitHub supports. GitHub recommends an authenticator app over SMS, and some organisations block members who use SMS.

Move GitHub 2FA to a new phone

If your authenticator app has a backup or a transfer feature, use that and every account moves at once. Our guides for Google Authenticator, Microsoft Authenticator and Authy cover each app. To move only GitHub, or to switch apps, re-add it from GitHub’s side while you can still sign in:

  • Go to Settings, then Password and authentication.
  • Under Two-factor methods, click Edit next to Authenticator app. If you have several methods, open the … menu next to it first.
  • Scan the new QR code with the app on your new phone, or click “setup key” and enter it manually.
  • Type the code from the new phone under “Verify the code from the app” and click Save.
  • Sign out and back in with the new phone to check, then delete the old GitHub entry from the old phone.

After you click Save, codes from the old phone stop working for GitHub, because the secret has changed. Do not wipe the old phone until the new one has signed you in.

GitHub 2FA code not working?

Almost every rejected code comes down to one of these. Check them in order.

  • The phone’s clock is off. Codes are made from the time, so set the date and time to automatic in your phone’s settings and try a fresh code.
  • The code changed while you typed it. Wait for a new code and enter it straight away.
  • You are reading the wrong entry. If you have more than one GitHub account, or an old entry from a previous setup, each has its own codes; use the one for the account you are signing in to.
  • The secret was replaced. If you or anyone else reset 2FA on the account, old entries in your app no longer work. Use a recovery code, then set the app up again.

Lost your phone? How to get back into GitHub

With a recovery code: go to github.com/login, enter your username and password, then under More options click 2FA recovery code and enter one of the codes. Once you are in, set up your authenticator app again on the new phone and generate a new set of recovery codes.

With an app backup: restore your authenticator app on the new phone and the GitHub codes come back. Nothing changes on GitHub’s side.

With neither: GitHub has an account recovery process. On the sign-in page, click 2FA recovery code, then Begin account or email recovery. You verify an email address and prove you own the account with a device you have signed in on before, an SSH key or a personal access token. GitHub reviews it and replies within about three business days. If you have none of those, GitHub Support cannot restore access, which is why the recovery codes matter.

Using U2 Secured Authenticator for GitHub

U2 Secured Authenticator is our app for iPhone and Android. On the free plan it makes unlimited 2FA codes, locks with Face ID or your fingerprint, and works with no signal, so GitHub and every other TOTP site are covered at no cost. It can also lock the moment you leave it and hide codes until you tap one, which helps when you are sharing your screen.

Premium, at $14.99 a year, adds an end-to-end-encrypted backup: your codes are encrypted on your phone before upload, and only your password or a recovery key you keep can open them, so the backup is zero-knowledge: we cannot read your codes. They restore on a new iPhone or Android phone, and the web portal shows live codes, read-only, in any browser. That last part helps when you are at a computer without your phone. On the free plan there is no cloud backup, so your GitHub recovery codes are your safety net.

Common questions

Which authenticator app should I use for GitHub?
Any app that supports TOTP codes, which is nearly all of them: Google Authenticator, Microsoft Authenticator, U2 Secured Authenticator and others. GitHub does not require a particular one. Pick one with a backup, or keep your recovery codes somewhere safe.
Is GitHub 2FA mandatory?
For accounts GitHub selects, yes. They get an email, then 45 days to enable it plus a 7-day grace period, after which the website is blocked until 2FA is on. Everyone else can turn it on voluntarily, and GitHub recommends it.
Where do I find my GitHub recovery codes?
Settings, then Password and authentication, then View next to Recovery codes. You can download, print or copy them there, or generate a new set, which cancels the old one.
Can I use SMS for GitHub 2FA?
In some countries. GitHub recommends an authenticator app instead, because texts can be intercepted, and some organisations do not allow members who use SMS.
Can I use GitHub 2FA without a phone?
Yes. A security key or a passkey on your computer works as a second method, and authenticator apps exist for desktop too. GitHub asks you to set up an authenticator app or SMS first, then add the others.
Does 2FA affect git push from the command line?
Not directly. Git over HTTPS uses a personal access token instead of your password, and SSH uses your SSH key, so you do not type a 2FA code when you push.
Can GitHub Support turn off 2FA if I am locked out?
No. GitHub says Support cannot restore access to an account with 2FA on if you have lost both your second factor and your recovery methods. The account recovery process works only if you can verify a device, SSH key or personal access token.

Sources

GitHub’s own documentation, with the date we last read it. GitHub changes its settings pages from time to time; if a label has moved, the docs below have the current one.

Free, unlimited 2FA codes

An authenticator app for iPhone and Android that works with GitHub and every other TOTP site, with an end-to-end-encrypted backup on Premium.

Get the authenticatorAsk us something