Git & SSH Configuration Guide

Secure Repository Integration: Local Machine to Gitea Server Instance

Part 1: Authentication

Generating & Adding an SSH Key to Gitea

Using SSH keys allows you to securely establish an authentication connection between your local computer and your Gitea server without having to input your password for every single operation.

Step 1.1: Generate a New SSH Key Pair

Open your local terminal and execute the following command. Make sure to replace the email address with the one linked to your Gitea account:

ssh-keygen -t ed25519 -C "your_email@example.com"

Note: If your system doesn't support Ed25519, fall back to RSA: ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

When prompted to "Enter a file in which to save the key," press Enter to accept the default file location. Next, choose a secure passphrase when prompted, or press Enter again to leave it blank.

Step 1.2: Start the SSH Agent & Add Key

Ensure the SSH agent is active in your terminal system background environment and securely register your private key:

# Start the ssh-agent in the background
eval "$(ssh-agent -s)"

# Add your private SSH key to the agent
ssh-add ~/.ssh/id_ed25519

Step 1.3: Copy your Public SSH Key

Print the contents of your public key file to the terminal window and copy the complete output text cleanly to your system clipboard:

cat ~/.ssh/id_ed25519.pub

Step 1.4: Link the Public Key to your Gitea Account Profile

Log in to your private or public Gitea web portal dashboard.
Click on your user avatar icon in the upper-right corner and select Settings from the menu list.
Navigate to the left-hand navigation sidebar menu and click on SSH / GPG Keys.
Locate the Manage SSH Keys section panel and click the Add Key button.
Provide a descriptive text name in the Key Name input field (e.g., "Work Laptop").
Paste your copied clipboard public key text explicitly into the main Content box.
Click the blue Add Key button to complete your registration interface workflow.

Part 2: Project Deployment

Initialize, Commit, and Push Your Project

With authorization parameters configured, you can execute standard local tree commits and securely stream your localized data elements to the repository server structure tracking layer.

Step 2.1: Initialize Git in your project folder

Open your terminal console window, navigate into your root target source project folder path, and initiate tracking structures:

git init

Step 2.2: Stage your project files

Add all file structures within your directory environment to the tracking indexes layer staging block:

git add .

Best Practice Note: If you maintain local dynamic transient artifacts, credential variables, or folders (such as node_modules/ or .env) that should not be published, construct a valid .gitignore configuration file prior to initiating staging.

Step 2.3: Create your first formal commit

Save snapshots of your staged data structures directly into your local storage database with an explicit context tag:

git commit -m "Initial commit"

Step 2.4: Set default branch target mapping

Standardized Gitea repositories utilize the main master nomenclature structure line. Force branch compliance targeting explicitly via:

git branch -M main

Step 2.5: Connect your local project to Gitea via SSH

Point your local git configuration tree parameters cleanly to your remote Gitea target via the SSH URL string:

git remote add origin git@gitea.yourdomain.com:username/repo-name.git

Step 2.6: Push your local repository to Gitea

Securely transfer your local commit stream upward to the tracking branches matrix. The -u flag sets up your upstream tracking profiles natively:

git push -u origin main

Quick Reference Sequence Command Matrix

For subsequent setup sequences, you can run this streamlined block after your public configuration registration is active:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin git@gitea.yourdomain.com:username/repo-name.git
git push -u origin main

Built for the Homelab Environment | Gitea Infrastructure Setup | 2026