Security Guides
Setting up GitHub two-factor authentication (2FA): authenticator app, passkeys, recovery codes, and what to do if you lose your phone
How to set up GitHub 2FA, based on GitHub Docs: authenticator app first, passkey as backup, storing recovery codes, recovering a lost device (up to 3 business days), switching from SMS.
Who this is for: people who want to add two-factor authentication (2FA: proving it is you with an app or a key on top of your password) to their own GitHub account, people who received GitHub's "enable 2FA" notice, and people who changed or lost their phone and can no longer produce a code. This guide is based on GitHub Docs, GitHub's official documentation, and uses the button labels exactly as they appear there.
Who has to use 2FA on GitHub
Since March 2023, GitHub has been rolling out mandatory 2FA, one group at a time, to users who contribute code on GitHub.com. GitHub Docs lists these triggers:
- Publishing an app or action for others
- Creating a release for your repository
- Contributing to specific high-importance repositories (such as projects tracked by the Open Source Security Foundation), or being an admin or contributor of one
- Being an owner of an organization that contains repositories or other users
- Being an admin or contributor of a repository that published one or more packages
- Being an enterprise administrator
GitHub notes that these criteria may change over time. Once your group is selected you get a notification email, a 45-day enrollment period starts, and banners appear on GitHub.com. If you never got the email you are not in a required group, but GitHub strongly recommends enabling 2FA anyway.
After the 7-day grace period, you cannot access GitHub.com until you enable 2FA. Existing personal access tokens (API tokens) and OAuth tokens keep working so that automation does not break. A locked account, however, cannot authorize new apps or create new tokens.
Email verification does not count as 2FA
Accounts without 2FA may be asked to confirm a new device with a code sent by email. GitHub Docs is explicit that this email check is not 2FA.
The reason: anyone who controls your inbox can both reset your password and pass the email check. The second factor has to be something separate from your email, such as an authenticator app or a passkey.
Which method to use
GitHub supports five 2FA methods. GitHub Docs recommends a TOTP authenticator app as the primary method and a passkey or security key as backup. If you have neither, it suggests GitHub Mobile as a good backup.
| Method | Can it be your first method? | GitHub Docs position | Notes |
|---|---|---|---|
| Authenticator app (TOTP) | Yes | Recommended primary method | GitHub recommends apps with cloud backup |
| SMS (text message) | Yes | Not recommended | Interceptable and not phishing-resistant; not available in every country |
| Passkey | No (after TOTP or SMS) | Recommended backup | Satisfies password and 2FA in one step |
| Security key | No (after TOTP or SMS) | Recommended backup | Counts only as a second factor, used with your password |
| GitHub Mobile | No (after TOTP or SMS) | Backup when you lack a passkey or key | You approve a push notification in the app |
TOTP (time-based one-time password) means an app that shows a new 6-digit number every 30 seconds. GitHub is app-agnostic, so Google Authenticator, Microsoft Authenticator, 1Password or any other TOTP app works.
Passkeys and security keys cannot be the first method because, according to GitHub Docs, they are easy to lose and sync across too narrow a range of devices for now. So the order is: enable 2FA with an authenticator app, then add a passkey.
Primary: authenticator app
A TOTP app on your phone, with its cloud backup turned on
Backup: passkey or security key
A passkey on your computer or a hardware key, so a lost phone does not lock you out
Last resort: recovery codes
16 codes, saved away from your phone, for example in a password manager
Setup steps (start with an authenticator app)
Install an authenticator app
Install a TOTP app on your phone or computer. GitHub Docs recommends one that backs up your codes to the cloud, so that a new device can produce the same codes after a phone change or loss.
Open Password and authentication
Click your profile picture in the upper-right corner of any GitHub page, then click Settings. In the Access section of the sidebar, click Password and authentication.
Enable 2FA and scan the QR code
In the Two-factor authentication section, click Enable two-factor authentication. Scan the QR code with your app and type the 6-digit code into the field under "Verify the code from the app."
If you cannot scan it, click setup key to see a code you can type into the app by hand.
Save the recovery codes and finish
Under "Save your recovery codes", click Download. Once they are saved, click I have saved my recovery codes to turn 2FA on. Where to keep them is covered in the next section.
Add a passkey as your second method
On the same page, under "Passkeys", click Add a passkey, confirm with your password or another method, and follow the prompts. Platform authenticators such as Windows Hello, Face ID and Touch ID can be registered as passkeys.
For a hardware security key, click Add next to "Security keys" and then Register new security key. For GitHub Mobile, sign in to the app and allow push notifications; the device then becomes available for 2FA.
Sign in with 2FA within 28 days
After you enable 2FA, your account enters a 28-day check-up period. A successful 2FA sign-in during that window ends it. If you reach day 28 without one, GitHub asks you to perform 2FA, and if that fails you must reconfigure your 2FA settings.
Storing your recovery codes
Recovery codes are one-time codes that let you back into your account when every 2FA method is unavailable. There are 16, and each one stops working once used.
Good places
- A password manager (GitHub Docs recommends this)
- A printed copy kept in a known place at home
- Encrypted external storage
Places to avoid
- Only on the same phone as your authenticator app (lose the phone and you lose both)
- Left in your Downloads folder (default name github-recovery-codes.txt)
- Sent to anyone over chat or email
To see them again later, click View next to "Recovery codes" on the Password and authentication page, then use Download, Print or Copy. Generating new recovery codes invalidates every code generated before, so save the new set right away.
GitHub Docs also lists SSH keys and personal access tokens as recovery methods. It recommends keeping GitHub.com cookies: if your browser wipes cookies every day, you will never have a verified device for recovery, because the _device_id cookie is what proves you used that device before.
If you lost or replaced your phone
What you still have decides whether you get back in immediately or wait for a review. Try these in order.
| What you still have | What to do | How long it takes |
|---|---|---|
| A recovery code | On the sign-in screen, More options, then 2FA recovery code | Immediate |
| A passkey or security key | Sign in with it | Immediate |
| An authenticator app backup | Restore the app on the new phone | Immediate |
| Your password plus a previously used device, an SSH key or a personal access token | More options, then Begin account or email recovery | Up to three business days for GitHub Support review |
| None of the above | The account cannot be recovered; unlink your email and use it with a new account | — |
Try a recovery code or passkey first
Go to https://github.com/login, enter your username and password, and when asked for 2FA open "More options". Choose 2FA recovery code and enter one code, or use your passkey. Once you are in, set up 2FA again on your new phone straight away.
If you have nothing, request account recovery
Under "More options", click Begin account or email recovery and enter the one-time password emailed to your addresses. Then choose a recovery verification factor: Verify with this device (a device you used with this account before), an SSH key, or a personal access token.
A member of GitHub Support reviews the request and emails you within three business days. Extra requests sent during that time are not reviewed. If you find your recovery codes or another 2FA method during the 3-5 day waiting period, you can use them at any time.
Some accounts cannot be restored even by GitHub Support
GitHub Docs states that, for security reasons, GitHub Support will not restore access to a 2FA-enabled account if you lose both your 2FA credentials and your recovery methods. SSH keys are also removed from accounts after a period of inactivity, so an old key may not count.
In that case the only option is to unlink your email address from the locked account and link it to a new or existing account. Set up your backup method and save your recovery codes on the day you enable 2FA.
Switching from SMS to an authenticator app
If you already use SMS, you can add or change methods without disabling 2FA. Because 2FA stays on, your recovery codes and your membership in organizations that require 2FA are kept.
Add the authenticator app
On Password and authentication, under "Two-factor methods", click Add next to the authenticator app (TOTP) method. Scan the QR code, enter the 6-digit code and click Save.
Make it your preferred method
Under "Two-factor authentication", in "Preferred 2FA method", choose the authenticator app from the dropdown. It becomes the method shown first at sign-in.
Remove SMS if you no longer need it
In the "Two-factor methods" list, remove SMS from the menu next to it. GitHub Docs tells members of organizations that block insecure methods to set up a secure method and then remove SMS. Before removing it, confirm that you can sign in with the app.
Some organizations lock out members who use SMS
Organization owners can enable "Only allow secure two-factor methods". GitHub Docs defines the secure methods as passkeys, security keys, authenticator apps and GitHub Mobile. In such an organization, a member with any SMS method configured cannot access organization resources.
Other settings to review while you are there
2FA protects sign-in. Tokens and keys you already issued, and apps you already authorized, remain separate ways into your account. Reviewing them on the same day takes only a few minutes more.
- Add a passkey
- Password and authentication, under "Passkeys", Add a passkey. Works as a 2FA backup and skips the password
- Use expiring tokens
- Settings, Developer settings, Personal access tokens, Fine-grained tokens, Generate new token. Pick an Expiration and limit repository access
- Prune authorized apps
- Settings, Applications, the Authorized OAuth Apps and Authorized GitHub Apps tabs. Revoke anything you do not recognize or no longer use
- Review SSH keys
- Settings, SSH and GPG keys. Delete keys you do not recognize or that are old
- Push protection for yourself
- Settings, Code security, "Push protection for yourself". Blocks pushes containing secrets to public repositories (on by default)
- Dependabot alerts
- Settings, Code security, Dependabot alerts, Enable all. You can also turn it on automatically for new repositories
- Security log
- Settings, Security log (in the Archives section). Lists actions from the last 90 days
Prefer fine-grained tokens over classic ones
A personal access token (PAT: a string used instead of a password for API and git operations) comes in two types, classic and fine-grained. GitHub recommends fine-grained tokens whenever possible, because a classic token reaches every repository in the organizations you can access and every repository in your personal account.
GitHub automatically removes tokens that have not been used for a year, but it still strongly recommends setting an expiration. If you only need GitHub from the command line, GitHub CLI or Git Credential Manager avoids creating a token at all. Why deleting a leaked token from a repository is not enough is covered in 543,699 credentials published on GitHub still worked.
Where secret scanning and push protection apply
Secret scanning (automatic detection of API keys and similar secrets in code) runs free and automatically on public repositories. Repository push protection is enabled under the repository's Settings, Advanced Security, by enabling Secret Protection and then Push protection.
Private repositories owned by an organization need the paid GitHub Secret Protection. Private repositories in a regular personal account are not covered. For those, a local pre-commit check such as gitleaks fills the gap.
For organization owners: require 2FA for members
In the organization's Settings, under Authentication security, select "Require two-factor authentication for everyone in your organization" and click Save. This is available on GitHub Free and GitHub Team plans. Adding "Only allow secure two-factor methods" also shuts out members who use SMS.
Once it is on, members without 2FA lose access to organization resources, and outside collaborators without 2FA are removed. Bots and service accounts count too, so tell people in advance and check who already uses 2FA on the People page before switching.
Checklist
| Task | Where | Time |
|---|---|---|
| Enable 2FA with an authenticator app | Settings, Password and authentication | 5 min |
| Save recovery codes in a password manager | Same page, Recovery codes, View | 2 min |
| Add a passkey or security key | Same page, Passkeys / Security keys | 3 min |
| Sign in with 2FA within 28 days | — | — |
| Replace classic tokens with expiring fine-grained ones | Settings, Developer settings | 5 min per token |
| Prune authorized apps and SSH keys | Settings, Applications / SSH and GPG keys | 5 min |
| Check push protection and Dependabot alerts | Settings, Code security | 2 min |
| If you own an organization, require 2FA | Organization Settings, Authentication security | A few days including notice |
Sources (public record)
The steps, periods and behavior in this guide were checked against GitHub Docs and other official pages on October 6, 2026. GitHub's screens and criteria change, so check the source pages before acting.
- Setting up 2FA: GitHub Docs, "Configuring two-factor authentication" / "Changing your two-factor authentication method" / "Countries where SMS authentication is supported"
- Mandatory 2FA: GitHub Docs, "About mandatory two-factor authentication" / GitHub Blog, "Raising the bar for software security: next steps for GitHub.com 2FA" (December 14, 2022)
- Recovery: GitHub Docs, "Configuring two-factor authentication recovery methods" / "Recovering your account if you lose your 2FA credentials"
- Tokens: GitHub Docs, "Managing your personal access tokens"
- Apps and SSH keys: GitHub Docs, "Reviewing your authorized OAuth apps" / "Reviewing and revoking authorization of GitHub Apps" / "Reviewing your SSH keys" / "Reviewing your security log"
- Secret scanning and Dependabot: GitHub Docs, "About secret scanning" / "Managing push protection for users" / "Enabling push protection for your repository" / "Configuring Dependabot alerts"
- Organization 2FA: GitHub Docs, "Requiring two-factor authentication in your organization"
Read next
- Choosing a method: Choosing MFA the right way: what "phishing-resistant" means, and why SMS is weak / Glossary: What is 2FA? / What is a passkey?
- When a token leaks: 543,699 credentials published on GitHub still worked (2026 study)
- Stop secrets before commit: Stop secrets before they commit with gitleaks
- Narrow key permissions: SSH key least privilege
- Where to host: Self-hosted Git vs GitHub: which is actually more secure?
FAQ
QWhere do I turn on two-factor authentication on GitHub?
Click your profile picture in the upper-right corner, choose Settings, then in the Access section of the sidebar click Password and authentication. In the Two-factor authentication section, click Enable two-factor authentication and set it up with an authenticator app (TOTP) or SMS. Passkeys, security keys and GitHub Mobile can be added after TOTP or SMS is configured.
QIs 2FA mandatory on GitHub?
Since March 2023, GitHub has been requiring 2FA, in groups, for users who contribute code on GitHub.com. Triggers include creating a release, publishing an app or action, being an admin or contributor of a repository that published packages, and owning an organization. Selected users get an email, a 45-day enrollment period and a 7-day grace period; after that, GitHub.com is unavailable until 2FA is enabled. Users who were not notified are not required to, but GitHub strongly recommends it.
QCan I use SMS for GitHub 2FA?
In supported countries, yes; GitHub publishes the list. But GitHub Docs strongly recommends a TOTP authenticator app instead, because SMS is susceptible to interception, not phishing-resistant and less reliable. Some organizations block members who have SMS 2FA configured.
QI lost or replaced my phone and cannot get a GitHub 2FA code. What now?
First look for your recovery codes (the default file name is github-recovery-codes.txt) and enter one via More options, then 2FA recovery code, on the sign-in screen. A registered passkey or security key also works. If you have none of these, choose Begin account or email recovery, verify an email one-time password, and prove your identity with a previously used device, an SSH key or a personal access token. GitHub Support reviews the request and emails you within three business days.
QI lost my recovery codes too. Can GitHub Support restore my account?
No. GitHub Docs states that, for security reasons, GitHub Support cannot restore access to a 2FA-enabled account if you lose your 2FA credentials and your recovery methods. At that point the account is lost; what you can do is unlink your email address from the locked account and use it with a new account.
QHow do I switch from SMS to an authenticator app?
In Password and authentication, under Two-factor methods, click Add next to the authenticator app (TOTP) method, scan the QR code, enter the 6-digit code and click Save. Then choose the app under Preferred 2FA method, and remove SMS if you no longer want it. You do not need to disable 2FA, so your recovery codes stay valid.