Codeberg 2FA: how to set up an authenticator app

Codeberg hosts Git repositories and runs on the forge software Forgejo (Codeberg). Two-factor authentication (2FA) is optional there, but Codeberg's docs suggest turning it on soon after you sign up (Codeberg). The docs describe two methods: codes from an authenticator app, which Codeberg calls TOTP, and hardware security keys, which you add once TOTP is set up.

Two details matter before you start: you get a single recovery key, not a list of backup codes, and a password reset won't get you past 2FA. This guide uses Authenticator App - Novaz on iPhone, but any authenticator app works the same way.

How we checked this guide: the Codeberg steps come from Codeberg's documentation and from the source code of the Forgejo build that codeberg.org runs today, which Codeberg publishes on its own site, all linked below. We read them on October 20 and 21, 2026. The screenshots in Codeberg's docs are older than the current screens, so the labels here come from the current code. We haven't tested the steps on a Codeberg 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

These steps follow Codeberg's guide, with today's labels (Codeberg, Codeberg source):

1. Sign in at codeberg.org, open the menu under your avatar at the top right, and choose Settings.
2. Choose Security.
3. In the Two-factor authentication (TOTP) section, select Enroll into two-factor authentication.
4. Codeberg shows a QR code. In Novaz, tap +, then Scan QR code, and point the camera at it. If the QR code is on the same iPhone, take a screenshot, tap +, then Choose a photo. See scanning a QR code on the same iPhone.
5. To type the key instead, find it after Or enter the secret:. In Novaz, tap +, then Enter key manually. Enter Codeberg as the Service, your username as the Account, and the secret as the Setup key. The secret is 64 characters long, so scanning is easier. See What is a 2FA setup key?
6. Type the 6-digit code from Novaz into Passcode and select Verify.
7. You're back on the Security page. A green message holds your single-use recovery key, in parentheses. Copy it now: Codeberg won't show it again.

The section should now say your account is currently enrolled. Codeberg emails you whenever TOTP is turned on or off (Codeberg source).

One recovery key with three names

Codeberg's docs call it a scratch token, the settings page calls it a single-use recovery key, and the sign-in screen calls it a scratch code. It's one code, and it works once. After you use it, Codeberg takes you to your security settings to make a new one (Codeberg source). You can also replace it at any time with Regenerate single-use recovery key, which cancels the old one.

If you lose the phone and have no Novaz backup to restore, this key is your only way back in. Keep it in a password manager or on paper. More in 2FA backup codes.

Signing in, and Git after 2FA

Codeberg asks for a code every time you sign in (Codeberg). Type it into Passcode and select Verify, or choose Use a scratch code. If you've added a security key, you can choose between the key and a code.

For Git over SSH, nothing changes. Over HTTPS, your password stops working for Git, so create an access token under Settings > Applications and use it as the password (Codeberg). Codeberg shows each token only once.

If Codeberg rejects your code

Codeberg accepts the code for the current 30-second window and the one before it, giving you at least 30 seconds (Codeberg). A code that has just worked can't be used again, so wait for the next one (Codeberg source). If every code fails, check the iPhone's clock: Settings > General > Date & Time > Set Automatically. Novaz warns you when the clock is 15 seconds or more off. More in Authenticator code not working?

Changing phones

Do this while you still have the old phone. On the Security page, select Re-enroll two-factor authentication, scan the new QR code with Novaz on the new iPhone, and verify a code. This replaces the old setup and gives you a new recovery key (Codeberg source). Then make sure the page still says enrolled. If you have a Novaz iCloud backup or backup file, you can restore your accounts on the new iPhone instead and keep the current setup. See How to transfer your authenticator app to a new iPhone.

If you lose your authenticator

Sign in with Use a scratch code and your recovery key, then use Re-enroll two-factor authentication to set up your new phone.

A password reset doesn't help: Codeberg's account recovery page also asks for a passcode or the scratch code (Codeberg source).

Without the recovery key, Codeberg's docs don't describe a recovery process. On Codeberg's community issue tracker, a member of Codeberg's executive board has told locked-out users to email contact@codeberg.org (Codeberg staff reply). A very small team handles user support in their spare time, and Codeberg's contact page warns, "Response times will be very long" (Codeberg). Codeberg doesn't publish what proof of ownership it asks for. More in Lost the phone with your authenticator app?

Turning 2FA off

On the Security page, select Disable two-factor authentication, then Yes to confirm (Codeberg source).

Official Codeberg help

• Setting up two-factor authentication
• Your First Steps on Codeberg
• Contact
• Need assistance with account recovery (Codeberg/Community issue tracker, staff reply)
• The Forgejo code deployed on codeberg.org: 2FA settings, 2FA sign-in, account recovery, English interface text