Skip to main content

Master Gitea SSH: The Ultimate Guide to Local & GitHub Repository Cloning

This comprehensive tutorial guides you through configuring Gitea and your local machine for secure cloning, pushing, and pulling repositories using SSH, covering both local repositories hosted on your Raspberry Pi and repositories mirrored from GitHub.

Blog Title Options​

If you plan to publish this guide, here are several strong title options:

  • Master Gitea SSH: The Ultimate Guide to Local & GitHub Repository Cloning
  • Secure Git Hosting: Set Up Gitea SSH for Seamless Local and Remote Pushes
  • No More Passwords: Configure SSH Keys for Gitea & GitHub Git Workflow

1. Prerequisites​

Before starting, ensure the following are true:

  1. Gitea is installed and running (with the SSH port, e.g., 222, exposed).
  2. Your Gitea user account is created.
  3. Git is installed on your local machine.

2. Decide and Prepare Your SSH Key 🔑​

You need a key pair to authenticate with Gitea. You can either use a key you already have or create a new one specifically for Gitea.

Option A: Use an Existing Key (e.g., ~/.ssh/id_ed25519)​

If you already use a default key for services like GitHub, you can reuse it.

  1. Identify your public key file. This is usually ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub.
  2. Make a note of the file's exact name (e.g., id_ed25519). You will need this name in the SSH Configuration step.

Creating a dedicated key avoids conflicts and simplifies management. This example uses id_gitea_raspi_key.

  1. Open your local terminal (Git Bash on Windows, Terminal on Linux/macOS).

  2. Run the key generation command, using the -f flag to specify the custom file name:

    ssh-keygen -t ed25519 -C "your_email@example.com-gitea-raspi" -f ~/.ssh/id_gitea_raspi_key

    When prompted for a Passphrase, enter a secure one.

This command creates two new files in your ~/.ssh/ directory: the private key (id_gitea_raspi_key) and the public key (id_gitea_raspi_key.pub).

3. Upload SSH Public Key to Gitea 📤​

You must upload the content of the public key file (.pub) to your Gitea profile.

  1. Copy the public key content. Replace YOUR_KEY_NAME with the name you chose in Step 2 (e.g., id_ed25519.pub or id_gitea_raspi_key.pub):

    cat ~/.ssh/YOUR_KEY_NAME.pub

  2. Access Gitea: Log into your Gitea instance in your browser.

  3. Navigate to your Profile Settings > SSH / GPG Keys.

  4. Click the "Add Key" button.

  5. Title: Give the key a name (e.g., Laptop Gitea Key).

  6. Content: Paste the entire content copied in step 1 into the text box.

  7. Click "Add Key".

4. Local SSH Configuration (The ~/.ssh/config file)​

Since your Gitea server uses a non-standard port (222), you must create an entry in your local ~/.ssh/config file. This allows you to use a simple nickname in your Git commands.

  1. Open or create the configuration file: ~/.ssh/config

  2. Add the following block, ensuring the IdentityFile line points to the private key file you decided to use in Step 2:

    Host gitea-server
      HostName [YOUR_RASPBERRY_PI_IP]
      Port 222
      User git
      # Point to your chosen PRIVATE key file (no .pub extension)
      IdentityFile ~/.ssh/YOUR_PRIVATE_KEY_NAME
      StrictHostKeyChecking no

    Example: If you used Option B, the line would be: IdentityFile ~/.ssh/id_gitea_raspi_key

  3. Save and close the file.

Testing the Gitea SSH Connection​

Test the connection using the nickname you just created:

ssh -T gitea-server

You should see a welcome message similar to: Hi your_username! You've successfully authenticated...

5. Cloning and Uploading Repositories 🚀​

A. Cloning a Gitea Repository​

Use your new configuration nickname to simplify the clone command:

# Simplified link using the 'Host' nickname from your config
git clone gitea-server:username/repo-name.git

B. Mirroring a GitHub Repository to Gitea via SSH​

This process copies a remote GitHub repository to your local Gitea instance.

  1. Create an Empty Repo on Gitea: First, create an empty repository with the desired name on your Gitea web interface.

  2. Clone the GitHub repository (using the --bare option is best for mirroring):

    git clone --bare git@github.com:original-user/repo.git
    cd repo.git

  3. Change the Remote Origin (to point to your Gitea server using the SSH nickname):

    git remote set-url origin gitea-server:your-gitea-username/repo-name.git

  4. Push the entire repository to Gitea:

    git push --mirror

    This command pushes all branches, tags, and history to your new Gitea repository.