GitHub's SMS codes: the country list, and the recovery you must set up first

What GitHub publishes about number type

No VoIP rule, no landline rule. GitHub frames the requirement around the device and the plan instead: “Make sure your device and cellular plan is capable of receiving Short Message Service (SMS) messages”, with the note that “Some 'data-only' phone plans and tablet devices connected to a cellular network may not support receiving text messages” (GitHub).

What GitHub does publish, and almost nobody else in this section does, is a country list. Its page of supported countries and regions for SMS authentication is explicit about the consequence: “If your country or region is not on this list, then we aren't currently able to reliably deliver text messages to your country”, and “If we don't support two-factor authentication via text message for your country of residence, you can set up authentication via a TOTP mobile application” (GitHub). The United States is on the list.

That list is the whole reason a US number keeps coming up for developers outside the US. GitHub's own comparison is blunt: “TOTP applications are more reliable than SMS, especially for locations outside the United States” (GitHub).

GitHub does not want you using SMS

• GitHub Docs, on configuring two-factor authentication

  “We strongly recommend using a TOTP application for two-factor authentication instead of SMS, and using security keys as backup methods instead of SMS.”

  https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication

• GitHub Docs, on why

  “SMS is susceptible to interception, does not provide resistance against phishing attacks, has unreliable deliverability, and is not supported in all countries.”

  https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication

There is an organisational catch too: “Organizations and enterprises have the ability to prevent content access to members who have SMS 2FA configured”, and “Outside collaborators may not enable SMS 2FA if their organization or enterprise has disallowed it” (GitHub). If you contract for a company that has switched that on, a phone number will not get you into their repositories whatever number it is.

What GitHub will and will not do when you are locked out

• GitHub Docs, on losing your 2FA credentials

  “GitHub Support will not be able to restore access to accounts with two-factor authentication enabled if you lose your two-factor authentication credentials”

  https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials

• GitHub Docs, on fallback numbers

  “Configuring a fallback SMS number in addition to your primary SMS number is no longer supported.”

  https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials

So the single number is a single point of failure by design. The things that actually get you back in are “the account's recovery codes file, SSH key(s), Personal access tokens (PATs) and verified device(s)” (GitHub), and even then “regaining access to your account by authenticating with a one-time password can take up to three business days” (GitHub). GitHub also states that “For security reasons, GitHub Support cannot assist with troubleshooting your 2FA methods, including SMS delivery” (GitHub).

Changing the number

GitHub lets you swap it without tearing 2FA down: “You can configure a different authenticator app or change your phone number, without disabling 2FA or creating a new set of recovery codes” (GitHub). The path, from the same page:

1. 01Profile picture → Settings.
2. 02In the Access sidebar, choose Password and authentication.
3. 03Under Two-factor methods, find the SMS method and choose Edit, then complete the CAPTCHA.
4. 04Select the country code, type the mobile number including the area code, and choose Send authentication code.
5. 05Type the code, choose Continue, then Save.

One small thing that trips people up: “If you need to edit the phone number you entered, you'll need to complete another CAPTCHA challenge” (GitHub). And separately, 2FA turns the new-device email check off entirely — “GitHub will not ask you to perform device verification when you have 2FA enabled, or when you sign in using a passkey” (GitHub).

Where a Cleat line fits

Narrowly, and honestly: when you are outside the US, GitHub cannot reliably text your country, and you want an SMS method as a *secondary* factor beside a TOTP app. A Cleat line is a real US mobile number in a country on GitHub's list, not VoIP, at $24.99 a month. For a team, the codes land in a shared inbox rather than on one person's phone, and webhooks and the API can put them where a process reads them. Getting a US number from outside the US covers every route, including the free ones.

When Cleat is the wrong answer here

• You can use a TOTP app. GitHub strongly recommends it over SMS, it works offline, and it is not country-gated. Do that first.
• Your organisation has disallowed SMS 2FA. No number will get you in. That is a policy on their side, not a delivery problem on yours.
• You have already lost your factors. GitHub Support will not restore access. Recovery codes, SSH keys, a personal access token or a verified device are the only ways back.
• You want a second GitHub account to get around something. One verified person per line; using it that way breaks GitHub's terms and ours.

Keep reading

AWS · Google Workspace · OpenAI · Every service in this section