Was ist Gitea?

Gitea ist ein leichtgewichtiger, self-hosted Git-Service, der auf unserer matzka.cloud-Infrastruktur unter git.matzka.cloud läuft. Es bietet eine GitHub-ähnliche Web-Oberfläche für Versionsverwaltung, Code-Review und Projekt-Management — vollständig unter eigener Kontrolle.

Architektur & Deployment

Gitea läuft als Docker-Container mit einer dedizierten PostgreSQL-Datenbank. Der Zugriff erfolgt über Traefik als Reverse Proxy mit automatischem SSL-Zertifikat.

Komponenten

Komponente	Container	Beschreibung
Gitea	gitea	Git-Service (gitea/gitea:1.22-rootless)
Datenbank	postgres-gitea	PostgreSQL 17 für Benutzer, Repos, Issues

Netzwerk-Architektur

Internet
  |
  v
Traefik (HTTPS, Let's Encrypt)
  |
  +-- git.matzka.cloud --> gitea:3000
  |
  +-- frontend (Docker Network)
  |
  +-- gitea-backend (intern)
  |     |
  |     +-- postgres-gitea:5432
  |
  +-- smtp-internal
        |
        +-- smtp-relay --> Mailcow (E-Mail-Benachrichtigungen)

Gesicherte Volumes

Folgende Volumes werden täglich um 03:00 UTC automatisch gesichert:

• postgres_gitea_data — Datenbank (Benutzer, Repos, Issues, Settings)
• gitea_data — Git-Repositories (bare repos)
• gitea_config — Konfiguration (app.ini)

Zugriff & Anmeldung

Web-Oberfläche

Die Gitea Web-UI ist erreichbar unter:

https://git.matzka.cloud

Melde dich mit deinem Gitea-Benutzerkonto an. Falls du noch kein Konto hast, wende dich an den Administrator.

Wichtige URLs

Funktion	URL
Web-UI	https://git.matzka.cloud
API (Swagger)	https://git.matzka.cloud/api/swagger
Repository-Übersicht	https://git.matzka.cloud/explore/repos
Benutzer-Einstellungen	https://git.matzka.cloud/user/settings

Repository erstellen & verwalten

Neues Repository über die Web-UI

1. Öffne https://git.matzka.cloud und melde dich an
2. Klicke auf das + Symbol oben rechts → Neues Repository
3. Fülle die Felder aus:
   • Repository-Name: z.B. mein-projekt
   • Sichtbarkeit: Privat oder Öffentlich
   • README initialisieren: Empfohlen
   • .gitignore: Passende Vorlage wählen
4. Klicke auf Repository erstellen

Bestehendes lokales Projekt hochladen

# Im Projektverzeichnis
cd mein-projekt

# Git initialisieren (falls noch nicht geschehen)
git init
git add -A
git commit -m "Initial commit"

# Gitea als Remote hinzufügen
git remote add gitea https://git.matzka.cloud/BENUTZERNAME/mein-projekt.git

# Pushen
git push -u gitea main

Git Workflow: Clone, Push, Pull

Repository klonen

# HTTPS (empfohlen)
git clone https://git.matzka.cloud/BENUTZERNAME/mein-projekt.git

# In das Verzeichnis wechseln
cd mein-projekt

Änderungen committen und pushen

# Status prüfen
git status

# Dateien stagen
git add -A

# Commit erstellen
git commit -m "feat: Neue Funktion hinzugefügt"

# Pushen
git push

Änderungen vom Server holen

# Aktuelle Änderungen holen und mergen
git pull

# Oder nur fetchen (ohne merge)
git fetch

Branches verwenden

# Neuen Branch erstellen und wechseln
git checkout -b feature/mein-feature

# Änderungen committen
git add -A
git commit -m "feat: Feature implementiert"

# Branch pushen
git push -u gitea feature/mein-feature

# Zurück zum main Branch
git checkout main

# Branch mergen
git merge feature/mein-feature
git push

Access Tokens für automatisierten Zugriff

Access Tokens ermöglichen passwortlosen Zugriff auf Gitea-Repositories. Das ist besonders nützlich für:

• Lokale Entwicklungsumgebungen (kein Passwort-Prompt bei jedem Push)
• CI/CD-Pipelines
• Automatisierte Skripte

Token über die Web-UI erstellen

1. Öffne https://git.matzka.cloud/user/settings/applications
2. Unter Access Tokens einen Namen vergeben (z.B. local-dev)
3. Berechtigungen wählen:
   • write:repository — Repository lesen und schreiben
   • read:user — Benutzerprofil lesen (optional)
4. Klicke auf Token generieren

Token über die Kommandozeile erstellen (Admin)

# Token mit Repository-Schreibzugriff erstellen
docker exec gitea gitea admin user generate-access-token \
  --username BENUTZERNAME \
  --token-name 'mein-token' \
  --scopes 'write:repository,read:user'

Token in der Remote-URL verwenden

# Remote mit Token konfigurieren
git remote set-url gitea \
  https://BENUTZERNAME:DEIN_TOKEN@git.matzka.cloud/BENUTZERNAME/repo.git

# Ab jetzt funktioniert push/pull ohne Passwort-Abfrage
git push gitea main

Multi-Remote Setup (GitHub + Gitea)

Ein Repository kann gleichzeitig auf GitHub und Gitea gespiegelt werden. So kombiniert man die Verfügbarkeit von GitHub mit der Datenkontrolle von Self-Hosted Gitea.

Zwei Remotes konfigurieren

# GitHub als origin (Standard)
git remote add origin https://github.com/BENUTZERNAME/mein-projekt.git

# Gitea als zweites Remote
git remote add gitea https://BENUTZERNAME:TOKEN@git.matzka.cloud/BENUTZERNAME/mein-projekt.git

# Remotes prüfen
git remote -v
# origin  https://github.com/BENUTZERNAME/mein-projekt.git (fetch)
# origin  https://github.com/BENUTZERNAME/mein-projekt.git (push)
# gitea   https://git.matzka.cloud/BENUTZERNAME/mein-projekt.git (fetch)
# gitea   https://git.matzka.cloud/BENUTZERNAME/mein-projekt.git (push)

Zu beiden Remotes pushen

# Einzeln pushen
git push origin main
git push gitea main

# Oder: Push-Alias in ~/.gitconfig definieren
# [alias]
#     pushall = !git push origin main && git push gitea main

Administration & Wartung

Benutzer verwalten

# Alle Benutzer auflisten
docker exec gitea gitea admin user list

# Passwort ändern
docker exec gitea gitea admin user change-password \
  --username BENUTZERNAME \
  --password NEUES_PASSWORT

Logs prüfen

# Gitea Container Logs
docker logs -f gitea

# Datenbank-Verbindung testen
docker exec postgres-gitea pg_isready -U gitea

Datenbank-Zugriff

# PostgreSQL Shell öffnen
docker exec -it postgres-gitea psql -U gitea -d gitea

# Beispiel: Repositories auflisten
SELECT id, owner_name, name, is_private, created_unix
FROM repository ORDER BY created_unix DESC;

Service-Übersicht

Aufgabe	Befehl
Neustart	cd /opt/docker/gitea && docker compose restart
Status prüfen	docker ps | grep gitea
Backup manuell	docker exec backup backup
Updates	Automatisch via Watchtower (sonntags 04:00 UTC)