SSH Keys and Authentication

Why Use SSH?

SSH key authentication lets you push and pull code without entering your password each time. It's more secure and convenient for daily development work.

Generating an SSH Key Pair

If you don't already have an SSH key, generate one:

On macOS / Linux

ssh-keygen -t ed25519 -C ""

Press Enter to accept the default file location. Optionally set a passphrase for additional security.

On Windows

Open Git Bash or PowerShell and run the same command:

ssh-keygen -t ed25519 -C ""

Adding Your SSH Key to MokoGitea

1. Copy your public key to the clipboard:

   # macOS
   cat ~/.ssh/id_ed25519.pub | pbcopy
   
   # Linux
   cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard
   
   # Windows (PowerShell)
   Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard

2. In MokoGitea, go to Settings → SSH / GPG Keys.
3. Click Add Key.
4. Enter a descriptive Key Name (e.g., "Work Laptop").
5. Paste your public key into the Content field.
6. Click Add Key.

Testing Your SSH Connection

ssh -T git@your-mokogitea-url

If successful, you'll see a message like: Hi username! You've successfully authenticated.

Cloning via SSH

Once your key is added, clone repositories using the SSH URL:

git clone git@your-mokogitea-url:owner/repo-name.git

HTTPS with Personal Access Tokens

If you prefer HTTPS over SSH, you can authenticate using a personal access token instead of your password:

1. Generate a token under Settings → Applications (see User Settings).
2. When prompted for a password during git push, enter your token instead.
3. To avoid re-entering it, configure Git's credential helper:

   git config --global credential.helper store

Troubleshooting

• Permission denied (publickey) — Ensure your public key is added to MokoGitea and the private key is loaded in your SSH agent (ssh-add ~/.ssh/id_ed25519).
• Wrong key used — If you have multiple keys, create an SSH config entry:

  Host mokogitea
    HostName your-mokogitea-url
    User git
    IdentityFile ~/.ssh/id_ed25519