Clone and push to Codeberg from your Mac using an SSH key you already have.

If you already have an SSH key and added it to your Codeberg account, you just need to set up your Mac. It takes only a few minutes.

Set Up SSH

First, make sure you have two files: a private key (no .pub ending) and a public key (ends with .pub). Never share your private key with anyone. Your public key is already on Codeberg, so leave it alone.

Now put the keys in the right place on your Mac. Open the terminal. Copy both files to the .ssh folder in your home folder. Let’s say your keys are called my_codeberg_key (private) and my_codeberg_key.pub (public), and they are in your current folder:

cp my_codeberg_key ~/.ssh/
cp my_codeberg_key.pub ~/.ssh/

After copying, you must set the correct permissions. Otherwise SSH will not work:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/my_codeberg_key
chmod 644 ~/.ssh/my_codeberg_key.pub

What these permissions mean:

  • chmod 700 ~/.ssh — Only you can read, write, and open this folder. No one else can enter it.
  • chmod 600 ~/.ssh/my_codeberg_key — Only you can read and write this private key file. No one else can see it.
  • chmod 644 ~/.ssh/my_codeberg_key.pub — You can read and write. Others can only read it. This is fine for a public key.

Next, tell SSH which key to use for Codeberg. Create or edit the file ~/.ssh/config:

nano ~/.ssh/config

Add these lines:

Host codeberg.org
    HostName codeberg.org
    User git
    IdentityFile ~/.ssh/my_codeberg_key

Save and exit (in nano: Ctrl+O, then Ctrl+X). Then set permissions for the config file:

chmod 600 ~/.ssh/config

Add Your Key to SSH Agent (Optional)

This step is optional because SSH can find your key without an agent if you already set up the ~/.ssh/config file correctly. Git will use the key directly from disk.

When do you need SSH agent?

  • If your private key has a password (recommended for security)
  • If you want to enter the password only once per session

When don’t you need it?

  • If your private key has no password (less secure)
  • Or if you are okay with entering the password every time you use Git

SSH agent keeps your key in memory. Without an agent, SSH reads the key from disk each time and asks for the password for every single push or pull.

First, make sure the SSH agent is running:

eval "$(ssh-agent -s)"

Option 1: Add to agent and save password in Keychain

ssh-add --apple-use-keychain ~/.ssh/my_codeberg_key

This adds the key to SSH agent and saves your key password in macOS Keychain. However, to make SSH automatically load the password from Keychain, you also need to update your ~/.ssh/config. Open it:

nano ~/.ssh/config

Add UseKeychain yes to your Codeberg host entry:

Host codeberg.org
    HostName codeberg.org
    User git
    IdentityFile ~/.ssh/my_codeberg_key
    UseKeychain yes

If you want this behaviour for all SSH connections, you can add a global entry at the top:

Host *
    UseKeychain yes

Now SSH agent will load your key automatically after restarting your Mac. You will enter the password only once, ever.

Option 2: Add to agent without Keychain

ssh-add ~/.ssh/my_codeberg_key

This adds the key to SSH agent, but your password is not saved anywhere. You will enter the password every time you restart your Mac or restart the SSH agent. The key stays loaded only until you log out.

Check which keys are loaded:

ssh-add -l

If you see your key in the list, it’s loaded and ready to use.

Test the Connection to Codeberg

Now test it:

ssh -T git@codeberg.org

If this is your first time connecting, the terminal will ask if you trust the server. Answer yes. If it works, you will see a welcome message with your username. It will also say you don’t get full shell access. That is normal.

If something goes wrong, first check your file permissions. Also check for typing mistakes in the config file. To debug, try connecting with the key directly:

ssh -i ~/.ssh/my_codeberg_key -T git@codeberg.org

If this works, your problem is in the config file, not the key itself.

Work with Git

After setup, you can clone and work with Codeberg repositories using SSH:

git clone git@codeberg.org:your_username/repository_name.git

What about the password? If you added your key to Keychain (ssh-add --apple-use-keychain), you will enter the password once. That’s it. If you did not use Keychain, you will enter the password each time you connect to Codeberg and after each restart. You choose: convenience (Keychain) or extra security (no saved password).