Codeberg Documentation

Getting Started with Codeberg
What is Codeberg? Your First Steps on Codeberg Install Git Your First Repository The Basics of Issue Tracking Integrated Wiki Email Settings Licensing on Codeberg Frequently Asked Questions
Collaborating with Others
Citable Code Pull requests and Git flow Invite Collaborators Create and Manage an Organization Repository Permissions Resolve Conflicts
Working with Git Repositories
Configuring Git Using .gitignore Clone & Commit via CLI Clone & Commit via Web Merge multiple commits into one Tags and Releases Working with large files
Writing in Markdown
Introduction to Markdown Using Links Topics Preformatted Text Using Images Using Lists Tables in Markdown Markdown FAQ
Security
Setting up two-factor authentication Adding an SSH key to your account Verifying you're connected to Codeberg using SSH fingerprints Adding a GPG key to your account
Codeberg Pages
Using Custom Domains Troubleshooting Example: Docs as Code with Sphinx Pushing output from SSGs into Codeberg Pages Redirects
Working with Codeberg's CI

Advanced Usage
Migrating Repositories Using Webhooks Generating an Access Token
Integrations with Other Services
Integrating with Keycloak Integrating with Matrix Integrating with Read the Docs
Codeberg Translate
Getting started Introduction to Weblate Manual Component configuration
Improving Codeberg
Contributing Code
Improving the Documentation
Style Guide How to create a new article? Can I preview my article? How to make screenshots for Codeberg Documentation? Documentation Contributor FAQ
Contact

Setting up two-factor authentication

Why two-factor authentication?

While it is important to have a strong password for extra security, it is a good idea to configure two-factor authentication for your account in case your password or device ever gets compromised.

With two-factor authentication, you will be asked for an authentication code generated using your phone in addition to your password when logging into Codeberg.

That way, your account cannot be compromised even if your password gets compromised, as long as your phone stays safe.

How to set up two-factor authentication

Prerequisites

You will need an authenticator app installed on your phone.

If you don't already have an authenticator app and you're not sure which app to use, have a look at Aegis Authenticator (F-Droid | Google Play Store) or Authenticator (App Store).

Step 1: Navigate to your user settings

User Settings

Step 2: Navigate to the Security tab and click on the Enroll button

Security Settings

Step 3: Scan the QR code and enter the verification code

Scanning QR Code

After scanning the QR code with your app, enter the six-digit code displayed in your app into the "Passcode" field of the settings form, then click "Verify".

Step 4: Store your scratch token in a safe place

If your phone ever breaks, gets lost or gets stolen, you can recover your account using the scratch token.

This is shown to you right after setting up 2FA:

Scratch token

Please store this token in a safe place.

Step 5: Done!

That's it - you have now configured two-factor authentication for your account.

From now on, each time you log into Codeberg you will be asked for an authentication code from your app, adding an extra layer of security over just using a password.

Personal access token

If you push to Codeberg via HTTP (see Clone & Commit via HTTP), an extra step will be needed to create a personal access token. This token will replace your normal password (+ authentication code) on Codeberg.

In your profile settings on Codeberg, go to the Applications tab. In the section Manage Access Tokens, add a Token Name and confirm by clicking on Generate Token.

applications

Make sure you keep the generated token in a safe place, because it will not be shown again.

token-created

When asked for your password, just enter the token.

You can create as many tokens as you'd like: one for each computer, one for each Git client, one for each session... you decide! You can also revoke tokens at any time by pressing Delete next to the token (see previous screenshot).

Configure Git with 2FA

If you want to clone a repository using the Git CLI and 2FA enabled, you have two choices:

  • use SSH: you do not have to do any special configuration, just use your ssh_key to login
  • use HTTPS: for the login you use your username and your generated accesstoken as a password. First time you enter it, it will be saved for your repository.
$ git clone https://codeberg.org/username/repo.git
Username for 'https://codeberg.org': username
Password for 'https://username@codeberg.org': access-token

If you want to permanently save your generated access token you can use the following command to store it globally on your computer:

git config --global credential.helper cache

Troubleshooting

Codeberg's instance of Forgejo is using an OTP library to generate 2FA tokens and follows the RFC 6238 standard to generate TOTP which uses 30 seconds long timeframes to accept your 2FA code.

  00:00     00:30     01:00
    v         v         v
    | <-----> | <-----> | <----->
         ^         ^         ^
     Previous   Current     Next

Codeberg's server is always at the Current period. If a token of the Previous period is submitted, which was generated between 00:00-00:30, it will be accepted, as long as that token was submitted between 00:30-01:00. So at a minimum you always got 30 seconds to submit the token, before it becomes "invalid" and Codeberg always accept two codes (Previous, Current)

Hey there! 👋 Thank you for reading this article!

Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?

You're invited to contribute to the Codeberg Documentation at its source code repository, for example, by adding a pull request or joining in on the discussion in the issue tracker.

For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.

© Codeberg Docs Contributors. See LICENSE