GitLab 2FA: how to set up an authenticator app
By the Novaz team · Updated October 29, 2026
Novaz steps checked against version 1.0.5
On this page
Your GitLab.com account holds your repositories, merge requests and CI/CD pipelines. Before you turn on two-factor authentication (2FA) there, know one thing: if you're on the Free plan and lose both your authenticator and your recovery codes, GitLab Support won't get you back in. You would have to start a new account (GitLab).
A second step is already mandatory on GitLab.com: since April 2026, password sign-ins without another method get a code by email each time (GitLab). An authenticator app replaces that email. Groups that require 2FA don't accept email codes, only an authenticator app or a WebAuthn device such as a YubiKey (GitLab). Passkeys are a further option (GitLab).
This guide uses Authenticator App - Novaz on iPhone, but any authenticator app works the same way. On a company's own GitLab server the steps match, but recovery goes through your administrator.
How we checked this guide: the GitLab steps come from GitLab's own documentation, support articles and blog, linked below, which we read on October 20, 2026. We haven't tested them on a GitLab account, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.
Turn on 2FA with an authenticator app
GitLab asks you to verify your email address first. Then (GitLab):
- On GitLab.com, select your avatar in the upper-right corner, then Edit profile.
- In the left sidebar, select Access > Password and authentication.
- In the One-time password authenticator section, select Register authenticator. GitLab shows a QR code and the details for adding the entry by hand.
- In Novaz, tap +, then Scan QR code, and point the camera at the screen. If GitLab is open on the same iPhone, take a screenshot and use Choose a photo instead. See scanning a QR code on the same iPhone.
- If scanning doesn't work, tap +, then Enter key manually, and type the key from GitLab's details as the Setup key. GitLab's docs don't name that field. See What is a 2FA setup key?
- Back in GitLab, enter your current password and the six-digit code Novaz shows, then select Register with two-factor app.
If the code was right, GitLab lists your recovery codes straight away.
Save your recovery codes
Use Download codes to save them as a file named gitlab-recovery-codes.txt, or copy and print them. Each code signs you in once (GitLab).
GitLab mentions cloud-backup apps, but it calls recovery codes your primary recovery method (GitLab). Novaz has a cloud backup too (iCloud backup, PRO) and a free backup file, but without one of them its keys are only on your iPhone. Save the codes either way, and store them away from that phone. See 2FA backup codes.
For a fresh set, select Regenerate recovery codes in the Recovery codes section and confirm with your password. The old set stops working. If you can't sign in but your account has an SSH key you still hold, run ssh git@gitlab.com 2fa_recovery_codes and answer yes: GitLab sends back new codes (GitLab).
Signing in afterwards
After your username and password, GitLab shows Enter authenticator app code. Type the code from Novaz and select Verify code. With several methods you can switch between them, and a passkey, if you've added one, is offered first (GitLab).
With 2FA on, your password no longer works for Git over HTTPS or the API. Use a personal access token, SSH, or an OAuth credential helper; an HTTP Basic: Access denied error usually means this (GitLab).
If GitLab rejects your code
GitLab links an invalid pin code error to a clock that's out of sync. On iPhone, open Settings > General > Date & Time and turn on Set Automatically. If it's already on, GitLab suggests switching it off and on again (GitLab). Novaz also warns you when the clock is 15 seconds or more off. Other causes are in Authenticator code not working?
Changing phones
GitLab's docs don't describe moving an authenticator to a new phone. While the old phone still makes codes, turn 2FA off (below), register again with the new phone, and save the new recovery codes. If you use Novaz's iCloud backup or a backup file, you can restore your accounts on the new iPhone instead and keep the same GitLab entry. See How to transfer your authenticator app to a new iPhone.
If you lose your authenticator
In order (GitLab):
- A recovery code. Select Recover your account on the two-factor screen and enter a code. Then set up 2FA again on your new phone.
- New codes over SSH, as described above.
- Another method you registered, such as a passkey or security key, which you can switch to at sign-in (GitLab).
After that, it depends on your plan. On Free, the answer is no: "GitLab Support cannot reset 2FA for Free accounts" (GitLab). That policy dates back to 2020 (GitLab).
In a paid (Premium or Ultimate) group, since September 15, 2026, you can't open the ticket yourself. The top-level group owner, who must be a support contact, files it with your email address and a Support PIN from their own account (GitLab). The troubleshooting page still describes filing your own ticket; the newer article replaces that. Neither page gives a timeframe. More in Lost the phone with your authenticator app?
Turning 2FA off
Under Access > Password and authentication, select Disable 2FA, enter your password, and confirm with Disable 2FA. A group may still require 2FA, and on GitLab.com password sign-ins fall back to the email code (GitLab). In Novaz, open the GitLab account and tap Remove account.
