I have two-factor authentication (2FA) enabled on most of my accounts using an authenticator app. Recently, while installing the app on another Android device, I tried to change the backup password, but it didn't work. As a result, I lost access, had to disable 2FA, and re-enable it using a different authenticator app.

Setting up 2FA again wasn't a problem because I was still logged in to most of my accounts. However, I didn't have my GitLab recovery codes. GitLab offers only two ways to regain access: receiving a six-digit verification code via email or generating new recovery codes using an SSH key associated with the account.

Receiving a verification code via email is the easiest way to recover your account, but having an SSH key can be incredibly useful when receiving an email verification code isn't an option.

Whenever I configure GitLab in my local environment, I create an SSH key for authentication and commit signing, as I always sign commits in my repositories. I described this process in a previous article.

Get New Recovery Codes

Check the SSH keys on your machine:

ls -la ~/.ssh

Look for files named like id_rsa, or id_ed25519.

Run the following command to get new recovery codes:

ssh -i ~/.ssh/id_ed25519 git@gitlab.com 2fa_recovery_codes

Replace id_ed25519 with the name of your SSH key file.

Copy one of the recovery codes
Go to the sign in page
Enter your username and password
Provide the recovery code when prompted

Now you're signed in! Disable 2FA and re-enable it—and don't forget to save your recovery codes somewhere safe this time.

StackFeed

GitLab 2FA Lockout: How My Local SSH Key Saved the Day