Gitea ›

SSH Key Setup Guide for Gitea

Prerequisite: Gitea SSH access requires cloudflared. If you haven't installed it yet, follow the Cloudflare Tunnel Setup guide first.

Verify that cloudflared is installed:

$ cloudflared --version
cloudflared version 2025.x.x ...

Then check if you already have an SSH key for Gitea:

$ ls ~/.ssh/id_ed25519_gitea.pub
Tip: If you already have id_ed25519_gitea.pub, skip to Step 3: Copy Key. Otherwise, continue to generate a new key.

Generate a dedicated SSH key for Gitea. Replace the email with your Gitea account email:

$ ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_gitea -C "your.name@datawords.asia"
Tip: We use a dedicated key (id_ed25519_gitea) instead of the default id_ed25519 so that each service has its own key. If one key is compromised, only that service is affected.

You will see the following prompts:

Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase): # Type a passphrase (recommended)
Enter same passphrase again: # Confirm passphrase
Important: A passphrase adds an extra layer of security. Even if someone gets your private key file, they cannot use it without the passphrase. We strongly recommend setting one.

After completion, two files will be created:

  • ~/.ssh/id_ed25519_gitea — your private key (never share this!)
  • ~/.ssh/id_ed25519_gitea.pub — your public key (this is what you'll add to Gitea)

Copy your public key to the clipboard. Use the command for your operating system:

macOS:

$ pbcopy < ~/.ssh/id_ed25519_gitea.pub

Linux (X11):

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

Linux (Wayland):

$ wl-copy < ~/.ssh/id_ed25519_gitea.pub

Windows (Git Bash):

$ clip < ~/.ssh/id_ed25519_gitea.pub

Or simply display the key and copy it manually:

$ cat ~/.ssh/id_ed25519_gitea.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... your.name@datawords.asia
Important: Make sure you copy the .pub file (public key). Never share or paste the file without .pub — that is your private key.

Open git.datawords.hk in your browser and log in.

Click your avatar in the top-right corner, then click Settings.

In the left sidebar, click SSH / GPG Keys.

In the "Manage SSH Keys" section, click "Add Key".

Fill in the form:

  1. Key Name: Enter a descriptive name (e.g. Work Laptop, MacBook Pro)
  2. Content: Paste your public key (the entire line starting with ssh-ed25519)

Click the green "Add Key" button.

Success! You should see your key appear in the SSH Keys list with its fingerprint.

Add the following to your SSH config file (~/.ssh/config) so Git knows which key to use and routes traffic through Cloudflare Tunnel:

Host git-ssh.datawords.hk
    HostName git-ssh.datawords.hk
    User git
    IdentityFile ~/.ssh/id_ed25519_gitea
    ProxyCommand cloudflared access ssh --hostname %h
Tip: If the file doesn't exist yet, create it. Make sure the file has the correct permissions: 
$ touch ~/.ssh/config
$ chmod 600 ~/.ssh/config

This configuration does three things:

  1. IdentityFile — tells SSH to use your Gitea-specific key
  2. ProxyCommand — routes the connection through Cloudflare Tunnel
  3. User git — automatically uses the git user for this host
Important: On Windows, replace ~/.ssh/ with C:\Users\YourName\.ssh\ in the IdentityFile path, and make sure cloudflared is in your system PATH.

Test your SSH connection to Gitea:

$ ssh -T git@git-ssh.datawords.hk
Hi your.name! You've successfully authenticated, but Gitea does not provide shell access.

If this is your first time connecting, you'll see a prompt about the server's fingerprint:

The authenticity of host 'git-ssh.datawords.hk (...)' can't be established.
ED25519 key fingerprint is SHA256:...
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

Type yes and press Enter to add the server to your known hosts.

You can now clone repositories using SSH:

$ git clone git@git-ssh.datawords.hk:YourOrg/your-repo.git

To switch an existing repository from HTTPS to SSH:

$ git remote set-url origin git@git-ssh.datawords.hk:YourOrg/your-repo.git

Done!

You can now push and pull from Gitea without entering your password. Your SSH key handles authentication automatically through Cloudflare Tunnel.

Problem Solution
Permission denied (publickey) Check that ~/.ssh/config has the correct IdentityFile path and that the public key is added to Gitea.
SSH asks for password instead of using key Make sure you're using the SSH URL (git@git-ssh.datawords.hk:...), not HTTPS. Check with git remote -v.
cloudflared: command not found Install cloudflared first. See the Cloudflare Tunnel Setup guide.
Connection timeout Check your internet connection. Cloudflare Tunnel requires outbound HTTPS access. Also verify the ProxyCommand line in ~/.ssh/config.
Key file permissions too open Fix permissions: chmod 600 ~/.ssh/id_ed25519_gitea and chmod 644 ~/.ssh/id_ed25519_gitea.pub
© 2026 Datawords Hong Kong