Press / to focus
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
Using .gitignore Configuring Git 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
Advanced Usage
Using Webhooks Generating an Access Token Migrating Repositories
Working with Codeberg's CI
Using Forgejo Actions (Self-hosted)
Integrations with Other Services
Integrating with Keycloak Integrating with Matrix Integrating with Read the Docs
Codeberg Translate
Getting started Manual Component configuration Introduction to Weblate
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

Adding an SSH key to your account

It is recommended to use one key per client. This means that if you access your Codeberg repository from your home PC, your laptop and your office PC you should generate separate keys for each machine.

Generating an SSH key pair

  1. Open Terminal on Linux/macOS, or Git Bash on Windows.

  2. Paste the text below:

    ssh-keygen -t ed25519 -a 100

    This will generate a new SSH key. You can also add a comment to help you identify the client with -C "comment here".

    > Generating public/private ed25519 key pair.

  3. When you're prompted to "Enter a file in which to save the key", press Enter. This accepts the default file location:

    > Enter file in which to save the key (/home/knut/.ssh/id_ed25519): [Press enter]

  4. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.

Your private key can be protected by a passphrase. This adds a layer of authentication that increases security. Be aware that this will only be helpful for certain attack scenarios and does not offer 100% protection. It is recommended to keep your private key safe and - well - private.

FIDO2 with OpenSSH

  1. Connect your security key and open a terminal

  2. Paste the text below

    ssh-keygen -t ed25519-sk

  3. If you have set one on your key, you'll be prompted for your FIDO2 PIN. Enter it to continue

  4. When you're prompted to "Enter a file in which to save the key", press Enter. This accepts the default file location.

  5. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.

Keep in mind that now, every time you wish to use Codeberg over SSH, you must have your security key plugged in and will be prompted to touch it to continue.

Add the SSH key to Codeberg

  1. Copy the SSH key to your clipboard. You must only copy the public key not the private one. You can identify it by the .pub suffix. By default, you can find the public key in $HOME/.ssh/id_ed25519.pub.

    On Linux you can use xclip on the command line. You may need to install it from your package manager.

    $ xclip -selection clipboard < ~/.ssh/id_ed25519.pub

    On Windows you can use clip.

    $ clip < ~/.ssh/id_ed25519.pub

    On macOS you can use pbcopy.

    $ pbcopy < ~/.ssh/id_ed25519.pub

    These commands will copy the contents of id_ed25519.pub (your SSH public key) to your clipboard.

    Alternatively you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.

  2. Navigate to your user settings

User Settings
  1. Go to the section SSH / GPG Keys and click on Add key.
SSH Key Settings
  1. Give an appropriate name for the key.
  2. Paste your key string into Content field.
  3. Click the Add key button.

You can always access your SSH public keys from https://codeberg.org/username.keys, substituting in your Codeberg username.

Test the SSH connection

Do this simple test:

$ ssh -T git@codeberg.org

The output should look like this:

Hi there, ____! You've successfully authenticated with the key named ____, but Forgejo does not provide shell access.
If this is unexpected, please log in with password and setup Forgejo under another user.

Note: All Codeberg users share a single Unix user named git which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access.

Verifying your SSH Key

Anyone can add a random SSH key; but fortunately, Codeberg provides a mechanism to verify that the key belongs to you. Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the added key is yours.

  1. Go to the SSH/GPG Keys tab in your Codeberg settings.
  2. Click on the Verify button next to the SSH key you would like to verify.
  3. Codeberg will show a token. Under its text box copy the command, and replace /path_to_your_private_key with the correct path of your private key.
  4. Copy the output, beginning with -----BEGIN SSH SIGNATURE----- and ending with -----END SSH SIGNATURE-----.
  5. Paste it into the large textbox and click the Verify button.

Avoid re-typing the passphrase

Assuming you've created a secure key with a passphrase, SSH will prompt you for your passphrase for every connection. Common desktop environments like macOS or GNOME will offer you to cache your passphrase via an SSH agent.

If you are working at the command line, you can alternatively do this directly:

$ eval $(ssh-agent)
$ ssh-add # enter your passphrase once, then it is cached.

Changing your repository's transport from HTTPS to SSH

  1. Go to the directory where your repository is located:

    cd /path/to/repository

  2. Look at the existing remotes with git remote :

    git remote -v

    It will look similar to this:

    origin	https://codeberg.org/knut/foobar.git (fetch)
origin	https://codeberg.org/knut/foobar.git (push)

    You might be using a different name than origin for your repository. If you do, remember to use that different name in the following steps.

  3. Run git remote set-url command followed by the remote name and the remote’s URL:

    git remote set-url <remote-name> <remote-url>

    For example, to change the URL of origin to git@codeberg.org:knut/foobar.git you would type:

    git remote set-url origin git@codeberg.org:knut/foobar.git

    Your HTTPS URL used this format: https://codeberg.org/<user>/<repo>.git The SSH URL uses this format: git@codeberg.org:<user>/<repo>.git (optionally with ssh:// at the beginning like this: ssh://git@codeberg.org:<user>/<repo>.git).

    Alternatively, you can find the SSH URL by going to your repository page on Codeberg (for example, going to https://codeberg.org/knut/foobar), clicking on SSH in the top right corner and copying the URL.

  4. Verify that your change was successful:

    git remote -v

    The output should look like this:

    origin	ssh://git@codeberg.org:knut/foobar.git (fetch)
origin	ssh://git@codeberg.org:knut/foobar.git (push)

Attribution
This guide is derived from GitHub Docs, used under CC-BY 4.0.

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