Update github-account-recovery-policy.md

[EarlyEdition]

Updating policy to the github account recovery. This PR was created in site-policy repo. (github/site-policy#1049)

1. Open a pull request directly in the GitHub Docs repo.

Why:

Closes: #37993
github/site-policy#1048

What's being changed (if available, include any code snippets, screenshots, or gifs):

This policy makes it clear that GitHub Support will not unlock accounts if the user has forgotten the account password, even if the user has access to two-factor authentication (2FA) and github recovery codes.

Check off the following:

• A subject matter expert (SME) has reviewed the technical accuracy of the content in this PR. In most cases, the author can be the SME. Open source contributions may require an SME review from GitHub staff.
• The changes in this PR meet the docs fundamentals that are required for all content.
• All CI checks are passing and the changes look good in the review environment.

[welcome]

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[github-actions]

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

• Spin up a codespace
• Set up a local development environment

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source	Review	Production	What Changed
site-policy/other-site-policies/github-account-recovery-policy.md	fpt	fpt

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

[Sharra-writes]

Hi! Thanks for opening a PR. I've never dealt with one of these before, and it looks like it's part of the process for working things out in site-policy. If you need me to play a role in that process, let me know! My job is mostly talking to people and asking questions, so I'm happy to do it for this, too. 💛

[EarlyEdition]

If you need me to play a role in that process, let me know! My job is mostly talking to people and asking questions, so I'm happy to do it for this, too. 💛

@Sharra-writes I appreciate your work and thank you for your effort.
May I ask you to talk to @margaret-tucker, the site-policy admin, to review my PR?

[Sharra-writes]

@EarlyEdition Sorry, this is a new process that I hadn't seen the steps for yet. I thought this process was for the site-policy repo, but it's actually more for ours. Let me dig in and figure out how to get this moved along!

Small thing: please don't ping people directly in here. One of my jobs is managing information flow so that things go where they need to and no one gets overwhelmed, which doesn't work if people are getting pinged. (You can always use the tick marks around a name to reference someone without actually pinging them.)

Anyway, I'll get going on this! Thanks for getting back to me.

[EarlyEdition]

@Sharra-writes I thank you for reviewing my PR. I'm not sure about changing the wording for clarity. I think having GitHub recovery codes is enough to recover the account. Otherwise what is the purpose of the account recovery form in GitHub support?

[Sharra-writes]

@EarlyEdition You might be right. I spent probably 10 minutes trying to figure that out. This comment from the original post is where I'm pulling the changes from:

I'm afraid that the 2FA credentials you may have are only valid as the second factor of authentication. For security reasons, they cannot (in any way) interact with the first factor of authentication; which would be the account password or, if lost, the account's primary email address for a password reset.

I think they're saying that the account recovery codes are only valid as a second form of authentication? It sounds like you must have either the password or access to the account's primary email, regardless of account recovery codes. How does that interact with the form? I don't know. I can definitely see how the form might be frustrating, because it seems to offer hope that there are other ways to recover an account, even though the documentation says that support won't do things like verify IDs, to prevent social engineering.

Let me know how you read that comment.

[EarlyEdition]

@Sharra-writes Thank you for your enlightening discussion and information. As far as I remember, GitHub account recovery form did not exist until last year. There is a contradiction between what support says and the account recovery policy. I am not saying that filling out the GitHub account recovery form alone proves the ownership of the account. However, access to 2FA and account recovery codes along with filling out the recovery form can prove the account ownership. I've created a ticket about two weeks ago to recover my old account, but I still haven't received any response from GitHub support.

[Sharra-writes]

@EarlyEdition This may be something where we need to rope in Support or someone from site-policy just to tell us what we should be asking for. Let me talk to the person who authored the new process for doing all this, because I'm also finding apparent inconsistencies in the internal documentation. I can't offer a timeline on that since he's out of office for a while, but if you hear back from Support, I would be very interested to know what they tell you.

[EarlyEdition]

@Sharra-writes I close this PR because GitHub support didn't respond to my ticket. I have been hoping to find my answer here but to no avail. I hope the site-policy admins can find the answer.

[Sharra-writes]

@EarlyEdition I'm sorry support hasn't been helpful. I'll still be looking into this regardless since, as I said, there seem to be some inconsistencies in the internal documentation that I need to clarify, and I also think the policy should be clearer since at the moment everyone seems confused by it.

[EarlyEdition]

@Sharra-writes As I've mentioned earlier, if you submit a ticket to support, they will respond within 24 hours. The reason they still haven't responded to my ticket after two weeks is because my account is new. The response I sent you earlier was for an old account that has been deleted. The full text was:

Hi Harold,

I'm afraid an older password is not something we can draw on, only the current password would be valid.

To your other comments, I'm afraid that the 2FA credentials you may have are only valid as the second factor of authentication. For security reasons, they cannot (in any way) interact with the first factor of authentication; which would be the account password or, if lost, the account's primary email address for a password reset.

Knowledge of the account's contents, access to previous devices, or history (including past passwords) are not something that is able to replace either of those two secure factors.

I understand this is not the answer you were hoping for but, at this time, the only method to regain access to that account would be if you can either recall the current password, or can regain access to the linked email address. If both of those options are unavailable to you, then I'm sorry to say the account must be considered lost.

Regards,

Mark

[Sharra-writes]

@EarlyEdition I'm glad they got back to you and clarified. I have a meeting scheduled to work on the internal end of things, so hopefully I can figure out how this new procedure is supposed to work.

[EarlyEdition]

@Sharra-writes If you agree with GitHub support, feel free to merge this PR. But the problem is not only the account recovery policy, but the recovery of the organization is also impossible. I can send you the link if you want.

[Sharra-writes]

@EarlyEdition It's not that simple. I don't have the power to unilaterally update site policy docs. They require a review from the legal team, and possibly support. There's a procedure for getting all that, but it's new, seems contradictory in some places, requires multiple steps, and, according to the site policy procedures, will likely result in the site policy team opening a PR internally to work out what should be said and how it should be said. That's why I have a meeting set up to work through some of the apparent contradictions.

[EarlyEdition]

@Sharra-writes Thank you for your kind cooperation. I'm asking site policy manager @jessephus to review this PR.

[EarlyEdition]

@Sharra-writes I received a message from support today.

Hello there,

Thanks for writing in to GitHub Support. It sounds like you're having trouble accessing an account with two-factor authentication ('2FA') enabled.

GitHub Support is unable to help with requests related to recovering access to an account with two-factor authentication enabled. This approach is designed to protect GitHub accounts from unauthorized access and to minimize the risk that GitHub staff are socially engineered into providing access to (or information about) an account that is protected by 2FA.

That said, I'd be happy to help by sharing some general information about accessing an account with 2FA enabled and where to begin if you need to explore account recovery.

Accessing an account with 2FA enabled

To access an account with 2FA enabled, you will need to provide the account password and an authentication code or proof from a 2FA method that was setup on the account (e.g. authenticator app, SMS number, or physical security key). In some cases, a passkey can be used for both factors of authentication, if one has already been setup on the account.

If you don't know the account password, you can request a password reset link. You will still need to provide a second factor of authentication to complete the password reset. GitHub Support is unable to advise which email address(es) are associated with an account because that information is private.

If you can't use any of the account's 2FA methods to sign-in, you'll need to use an account recovery code or try requesting a reset.

Using an account recovery code

When 2FA is setup, GitHub provides a set of emergency account recovery codes that can be used to access the account when the main 2FA methods are lost, inaccessible, or not functional.

Even if you think you might not have them, you may have saved these recovery codes to a password manager or somewhere on one of your devices. The default filename for these codes is github-recovery-codes or github-recovery-codes.txt.

Finding these codes may be your only way to get back into the account. For more information about using a recovery code, see Using a two-factor authentication recovery code.

Requesting a reset

You can try requesting a reset. Unlike account recovery codes, the ability to request a reset depends on whether or not you have interacted with the account recently and can prove it through a secure method. These methods include verified devices, SSH keys, and personal access tokens. You can request a reset even if you don't know the account password. Reset requests are individually reviewed by GitHub Support within 3-5 business days.

You can check what options are available to you after signing in and verifying a primary or backup email address. If you don't know the account password, you can begin a request by first requesting a password reset email and following the prompts after accessing the link. If you don't have access to a primary or backup email address associated with the account, you won't be able to request a reset. This applies if you have already disconnected your email address from the account, as disconnection is a permanent action. In this situation, you can only use an account recovery code.

GitHub Support can't check this or submit a request for you. In some cases, an option might not be available for use, depending on a number of factors. These factors are designed to ensure accounts are not accessed improperly. If no options are available to you, you can only use an account recovery code.

For more information and to get started with a reset request, see Authenticating with a verified device, SSH token, or personal access token.

Reclaiming your email address

If you can't use a recovery code or submit or recovery request yourself, the account is not recoverable.

Our approach to account recovery is outlined in the GitHub Account Recovery Policy and can't be modified. GitHub Support cannot grant an exception to this policy.

In this situation, you can disconnect a primary or backup email address from the account which will let you use it with another one. To get started, see unlinking your email address.

Other content from the account—including repositories, Gists, access permissions, and the account username—are not transferrable to a different account. Commits authored by your email address will be re-connected to your new account, but there may be additional steps required for those commits to appear on your new contribution graph.

Getting help with something else

If you need help with a different 2FA issue – such as ending a paid subscription on an unrecoverable account – reply here with additional details of your issue and we'll be happy to help.

For clarity, the options for account recovery that have been set out here are full and complete. There are no alternative account recovery methods and GitHub staff have no discretion or ability to assist with account recovery. Responses from you that are primarily related to seeking an alternative recovery pathway that has not been outlined here may not receive a reply from GitHub Support. That said, we'd be more than happy to help with a different related issue, if you have one.

Regards,

Zach