GitLab Two-Factor Authentication: Codes, Backups and Fixes

GitLab two-factor authentication adds a second code to your sign-in. The safest setup is an authenticator app plus saved backup codes, with text messages only as a fallback.

What GitLab offers

Two-factor supports an authenticator app or a WebAuthn device, with recovery codes.

Two-factor methods compared

Turn it on the safe way

1. Open GitLab's security settings and choose two-factor or two-step verification.
2. Pick the authenticator app option if there is one, and scan the QR code with an app such as Google Authenticator or Microsoft Authenticator.
3. Enter the 6-digit code the app shows to confirm.
4. Save the backup or recovery codes somewhere offline, such as a password manager or on paper.
5. Add text messages only as a backup method.

When the code does not work or arrive

• Authenticator codes depend on the clock: set your phone's date and time to automatic.
• Text codes can land in spam or "unknown senders"; check there before asking again.
• Ask for a new text code once, then wait; repeated requests can lock you out for a while.
• Use a backup code if nothing else works.

Lost your phone?

Recovery codes restore access; if they are lost too, GitLab support has an account recovery process. If you have neither the phone nor the codes, GitLab's account recovery process is the way back, and it can take days.

Should you use a second number for two-factor?

Prefer an authenticator app: it works without signal and cannot be stolen by a SIM swap. If GitLab only offers text messages and you want them on a separate number, use a number you keep for months, never a one-time number, because that number goes to someone else afterwards.

FAQ

Is text-message two-factor on GitLab safe?

It is much better than no two-factor, but an authenticator app or security key is safer, because text codes can be intercepted after a SIM swap.

What are backup codes?

One-time codes you save when you turn on two-factor. Each works once and gets you in when your phone is not available.

Can I turn off two-factor on GitLab?

Yes, from the security settings after you sign in, but it makes the account easier to take over.

What if I lost my authenticator app?

Sign in with a backup code and set it up again. Without codes, use the account recovery process.

Can I move my authenticator to a new phone?

Yes: most authenticator apps can transfer or back up accounts. Do it before you reset the old phone.

Why does GitLab ask for a code every time?

Clearing cookies or using private browsing makes the device look new. Allow cookies and choose to trust the device if offered.

Related: GitLab phone verification · GitLab code not received · verification code not received on any app.