Gitea - Getting Started Guide

Step 1 - Verify Gitea Works

Your server's IP address and root password are shown on the Server Details page in your client panel. Gitea is available immediately after the server is created. Open https://your.server.ip in a browser to verify it works.

Gitea login:

• Username: admin
• Password: the Admin Password you entered during the order

Gitea uses a self-signed SSL certificate by default. Your browser will show a security warning - click Advanced > Proceed (or Accept the Risk in Firefox). This is expected and safe. You can install a proper Let's Encrypt certificate later (see Step 4).

If you placed the server behind a VyOS router on a private network, either configure port forwarding (ports 22, 80 and 443) to make Gitea accessible from the internet, or connect over a VPN and reach Gitea on the server's private IP.

Step 2 - Create Your First Repository

Click the + button in the top right corner and select New Repository. Fill in the repository name and click Create Repository.

Clone your repository using HTTPS or SSH:

# HTTPS
git clone https://your.server.ip/admin/my-repo.git

# SSH (add your public key in Settings > SSH/GPG Keys first)
git clone git@your.server.ip:admin/my-repo.git

Git SSH uses port 22 (the standard SSH port). Gitea automatically manages SSH keys - when you add a public key in the web interface, it becomes available for Git operations immediately.

Step 3 - Set Up a Custom Domain

To use Gitea on your own domain instead of the server IP:

1. Create a DNS A record pointing your domain to the server IP:

   Type	Name	Value
   A	git	your.server.ip

2. SSH into your server and edit the Gitea config:

   nano /etc/gitea/app.ini

   Update these lines in the [server] section:

   DOMAIN     = git.yourdomain.com
   SSH_DOMAIN = git.yourdomain.com
   ROOT_URL   = https://git.yourdomain.com/

3. Update Nginx and restart services:

   sed -i "s/server_name .*/server_name git.yourdomain.com;/g" /etc/nginx/sites-available/gitea
   systemctl restart gitea
   systemctl reload nginx

DNS changes usually take a few minutes, but can take up to 24 hours. Check at dnschecker.org.

Step 4 - Enable Let's Encrypt SSL

Once your domain points to the server, replace the self-signed certificate with a free Let's Encrypt certificate. Connect via SSH and run:

/opt/setup/get-ssl.sh git.yourdomain.com

The script verifies DNS, obtains a certificate, configures Nginx for HTTPS, and updates the Gitea config automatically. The certificate renews automatically.

Make sure your domain's A record has propagated before running the script. SSL is optional - Gitea works fine with the self-signed certificate.

Step 5 - CI/CD with Gitea Actions

Your Gitea instance comes with a built-in CI/CD runner (Gitea Actions). It is compatible with GitHub Actions workflow syntax. To use it, create a workflow file in your repository:

.gitea/workflows/build.yaml

Example workflow:

name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Gitea Actions!"

The runner executes jobs directly on the host (no Docker required). Check runner status:

systemctl status act_runner

Fail2Ban - Brute-Force Protection

Your server comes with Fail2Ban pre-configured to protect both SSH and the Gitea web interface from brute-force attacks.

Rule	Max Attempts	Ban Duration
SSH	5 failed logins	1 hour
Gitea web login	5 failed logins	1 hour

Useful commands:

# Check banned IPs
fail2ban-client status sshd
fail2ban-client status gitea

# Unban an IP
fail2ban-client set sshd unbanip 1.2.3.4
fail2ban-client set gitea unbanip 1.2.3.4

If you accidentally lock yourself out, connect via VNC console in your client panel and unban your IP.

Updates

Gitea is installed as a standalone binary and does not update automatically. To update manually, download the new version and replace the binary:

# Download new version (replace X.Y.Z with the desired version)
wget -O /tmp/gitea https://dl.gitea.com/gitea/X.Y.Z/gitea-X.Y.Z-linux-amd64
chmod +x /tmp/gitea

# Replace binary and restart
systemctl stop gitea
cp /tmp/gitea /usr/local/bin/gitea
systemctl start gitea

OS updates can be applied via SSH:

apt update && apt upgrade -y

Server Credentials

Gitea admin credentials are stored in /root/.gitea_credentials. You can also see them when you connect via SSH (displayed in the welcome message).

Service Management

# Service status and control
systemctl status gitea          # check Gitea status
systemctl restart gitea         # restart Gitea
systemctl status nginx          # check Nginx (reverse proxy)
systemctl reload nginx          # reload Nginx after config change
systemctl status act_runner     # check CI/CD runner

# Gitea admin CLI
sudo -u git gitea admin user list --config /etc/gitea/app.ini
sudo -u git gitea admin user change-password --username admin --password "newpass" --config /etc/gitea/app.ini

# Database backup (SQLite)
cp /var/lib/gitea/data/gitea.db /root/gitea-backup-$(date +%Y%m%d).db

# Logs
tail -f /var/lib/gitea/log/gitea.log     # Gitea application log
journalctl -u gitea -f                    # systemd journal
tail -f /var/log/nginx/error.log          # Nginx errors

Software Included

Component	Details
Ubuntu	24.04 LTS
Gitea	1.25 (SQLite, Git LFS)
Nginx	Reverse proxy with SSL
Gitea Actions Runner	Built-in CI/CD (host executor)
Certbot	Let's Encrypt SSL
Fail2Ban	SSH + Gitea brute-force protection

• Gitea Documentation: docs.gitea.com
• Gitea Actions Guide: docs.gitea.com/usage/actions/overview
• Gitea on GitHub: github.com/go-gitea/gitea