From 04c668eb7b54e601224911a0c5a4a54fc8bc9012 Mon Sep 17 00:00:00 2001 From: Administrator Date: Tue, 24 Feb 2026 08:17:57 +0000 Subject: [PATCH] docs: create IT_Abteilung/DatenBank/Gitea --- IT_Abteilung/DatenBank/Gitea.md | 1834 +++++++++++++++++++++++++++++++ 1 file changed, 1834 insertions(+) create mode 100644 IT_Abteilung/DatenBank/Gitea.md diff --git a/IT_Abteilung/DatenBank/Gitea.md b/IT_Abteilung/DatenBank/Gitea.md new file mode 100644 index 0000000..c6dfb9f --- /dev/null +++ b/IT_Abteilung/DatenBank/Gitea.md @@ -0,0 +1,1834 @@ +--- +title: Gitea Profice Dokumentation +description: +published: true +date: 2026-02-24T08:17:55.412Z +tags: +editor: markdown +dateCreated: 2026-02-24T08:17:55.412Z +--- + +# Gitea – Vollständige Server-Dokumentation + +> **Systemumgebung:** Debian-basierter Server (Debian 12 / Ubuntu 22.04+) +> **Datenbank:** PostgreSQL 16 (lokal installiert) +> **Wiki-Anbindung:** Wiki.js +> **Einsatz:** Selbst gehostete Git-Plattform für Versionsverwaltung, Code-Review und CI/CD + +--- + +## Inhaltsverzeichnis + +1. [Überblick und Architektur](#1-überblick-und-architektur) +2. [Installation](#2-installation) +3. [Grundkonfiguration (app.ini)](#3-grundkonfiguration-appini) +4. [PostgreSQL-Anbindung](#4-postgresql-anbindung) +5. [Reverse Proxy und SSL](#5-reverse-proxy-und-ssl) +6. [Benutzerverwaltung](#6-benutzerverwaltung) +7. [Repositories verwalten](#7-repositories-verwalten) +8. [Branches, Tags und Releases](#8-branches-tags-und-releases) +9. [Issues und Projektplanung](#9-issues-und-projektplanung) +10. [Pull Requests und Code-Review](#10-pull-requests-und-code-review) +11. [CI/CD mit Gitea Actions](#11-cicd-mit-gitea-actions) +12. [Wiki-Funktion und Wiki.js-Anbindung](#12-wiki-funktion-und-wikijs-anbindung) +13. [SSH-Zugang und Authentifizierung](#13-ssh-zugang-und-authentifizierung) +14. [Webhooks und Integrationen](#14-webhooks-und-integrationen) +15. [Pakete und Container Registry](#15-pakete-und-container-registry) +16. [Datensicherung und Wiederherstellung](#16-datensicherung-und-wiederherstellung) +17. [Wartung und Updates](#17-wartung-und-updates) +18. [Sicherheitshärtung](#18-sicherheitshärtung) +19. [Fehlerbehebung](#19-fehlerbehebung) +20. [Schnellreferenz – Befehle auf einen Blick](#20-schnellreferenz--befehle-auf-einen-blick) + +--- + +## 1. Überblick und Architektur + +### Was ist Gitea? + +Gitea ist eine leichtgewichtige, selbst gehostete Git-Plattform, geschrieben in Go. Sie bietet eine ähnliche Funktionalität wie GitHub oder GitLab, benötigt aber deutlich weniger Ressourcen. Gitea umfasst Versionsverwaltung, Issue-Tracking, Code-Review über Pull Requests, CI/CD (Gitea Actions), eine Paket-Registry und vieles mehr. + +### Kernfunktionen + +| Funktion | Beschreibung | +|---|---| +| **Git-Repositories** | Erstellen, klonen, pushen, branchen – vollständiges Git-Hosting | +| **Issue-Tracker** | Aufgaben, Bugs und Feature-Requests verwalten | +| **Pull Requests** | Code-Review mit Diff-Ansicht, Kommentaren und Freigaben | +| **Gitea Actions** | CI/CD-Pipelines (kompatibel mit GitHub Actions) | +| **Wiki** | Integriertes Wiki pro Repository | +| **Paket-Registry** | Docker, npm, PyPI, Maven, NuGet und weitere | +| **Organisationen** | Team- und Rechteverwaltung | +| **Webhooks** | Ereignisgesteuerte Integrationen | + +### Architektur auf diesem Server + +```plantuml +@startuml + +skinparam shadowing false +skinparam roundCorner 10 + +package "Debian Server" { + + [Reverse Proxy\n(Nginx/Caddy)] as proxy + [Gitea\n(Git-Server)] as gitea + [Wiki.js\n(Dokumentation)] as wiki + + package "PostgreSQL 16" { + database "DB: gitea" as db_gitea + database "DB: wikijs" as db_wiki + } + + proxy --> gitea : HTTPS + proxy --> wiki : HTTPS + gitea --> db_gitea : Daten + wiki --> db_wiki : Daten + wiki --> gitea : Git-Sync +} + +cloud "Benutzer" { + [Browser] as browser + [Git CLI] as git_cli + [IDE / Editor] as ide +} + +browser --> proxy : HTTPS +git_cli --> gitea : SSH / HTTPS +ide --> gitea : SSH / HTTPS + +@enduml +``` + +### Systemvoraussetzungen + +| Komponente | Minimum | Empfohlen | +|---|---|---| +| RAM | 256 MB | 1 GB+ | +| CPU | 1 Kern | 2+ Kerne | +| Speicherplatz | 1 GB | 10 GB+ (je nach Repositories) | +| Go | Nicht nötig (Binär) | – | +| Git | 2.0+ | Aktuelle Version | +| PostgreSQL | 12+ | 16 (bereits installiert) | + +--- + +## 2. Installation + +### 2.1 Systembenutzer erstellen + +Gitea läuft unter einem eigenen Systembenutzer: + +```bash +# Benutzer erstellen (ohne Login, mit Home-Verzeichnis) +sudo adduser --system --shell /bin/bash --gecos 'Gitea' \ + --group --disabled-password --home /home/gitea gitea +``` + +### 2.2 Verzeichnisse anlegen + +```bash +# Arbeitsverzeichnisse erstellen +sudo mkdir -p /etc/gitea +sudo mkdir -p /var/lib/gitea/{custom,data,log} + +# Berechtigungen setzen +sudo chown -R gitea:gitea /var/lib/gitea +sudo chmod -R 750 /var/lib/gitea + +# Konfigurationsverzeichnis (Gitea braucht Schreibrechte bei der Ersteinrichtung) +sudo chown root:gitea /etc/gitea +sudo chmod 770 /etc/gitea +``` + +### 2.3 Git installieren + +```bash +sudo apt install -y git +git --version +``` + +### 2.4 Gitea-Binärdatei herunterladen + +```bash +# Aktuelle Version ermitteln (Beispiel: 1.22) +GITEA_VERSION="1.22.6" + +# Binärdatei herunterladen +sudo wget -O /usr/local/bin/gitea \ + "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64" + +# Ausführbar machen +sudo chmod +x /usr/local/bin/gitea + +# Version prüfen +gitea --version +``` + +> **Tipp:** Die aktuelle Version findet man unter [dl.gitea.com/gitea](https://dl.gitea.com/gitea/) oder auf [github.com/go-gitea/gitea/releases](https://github.com/go-gitea/gitea/releases). + +### 2.5 Systemd-Service erstellen + +```bash +sudo nano /etc/systemd/system/gitea.service +``` + +```ini +[Unit] +Description=Gitea (Git with a cup of tea) +After=syslog.target +After=network.target +After=postgresql.service +Requires=postgresql.service + +[Service] +Type=simple +User=gitea +Group=gitea +WorkingDirectory=/var/lib/gitea +RuntimeDirectory=gitea +ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini +Restart=always +RestartSec=5 +Environment=USER=gitea HOME=/home/gitea GITEA_WORK_DIR=/var/lib/gitea + +# Sicherheitshärtung +CapabilityBoundingSet=CAP_NET_BIND_SERVICE +AmbientCapabilities=CAP_NET_BIND_SERVICE +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=full + +[Install] +WantedBy=multi-user.target +``` + +```bash +# Service aktivieren und starten +sudo systemctl daemon-reload +sudo systemctl enable gitea +sudo systemctl start gitea + +# Status prüfen +sudo systemctl status gitea +``` + +### 2.6 Ersteinrichtung über den Web-Installer + +Nach dem Start ist der Web-Installer erreichbar unter: + +``` +http://SERVER_IP:3000/install +``` + +Hier werden die Grundeinstellungen festgelegt: +- Datenbanktyp und Verbindung (PostgreSQL) +- Site-Titel und Domain +- Administrator-Konto + +> **Hinweis:** Nach der Ersteinrichtung die Berechtigungen des Konfigurationsverzeichnisses einschränken: +> ```bash +> sudo chmod 750 /etc/gitea +> sudo chmod 640 /etc/gitea/app.ini +> ``` + +--- + +## 3. Grundkonfiguration (app.ini) + +Die Hauptkonfiguration von Gitea liegt in `/etc/gitea/app.ini`. Die Datei folgt dem INI-Format mit Sektionen. + +### 3.1 Wichtige Sektionen + +```ini +; =========================================================== +; /etc/gitea/app.ini – Hauptkonfiguration +; =========================================================== + +; ---------- Allgemein ---------- +APP_NAME = Gitea: Git-Server +RUN_MODE = prod +RUN_USER = gitea +WORK_PATH = /var/lib/gitea + +; ---------- Repository-Einstellungen ---------- +[repository] +ROOT = /var/lib/gitea/repositories +DEFAULT_BRANCH = main +DEFAULT_PRIVATE = public +MAX_CREATION_LIMIT = -1 ; -1 = unbegrenzt +DISABLED_REPO_UNITS = ; Keine Funktionen deaktivieren +DEFAULT_REPO_UNITS = repo.code,repo.issues,repo.pulls,repo.wiki,repo.releases,repo.projects +ENABLE_PUSH_CREATE_USER = true ; Repo per Push erstellen +ENABLE_PUSH_CREATE_ORG = true + +; ---------- Server ---------- +[server] +PROTOCOL = http +DOMAIN = git.example.de +HTTP_ADDR = 127.0.0.1 +HTTP_PORT = 3000 +ROOT_URL = https://git.example.de/ +SSH_DOMAIN = git.example.de +SSH_PORT = 22 +START_SSH_SERVER = false ; System-SSH verwenden +LFS_START_SERVER = true ; Git LFS aktivieren +LFS_JWT_SECRET = ; Wird automatisch generiert +OFFLINE_MODE = false +LANDING_PAGE = explore ; Startseite: explore, home, login + +; ---------- Datenbank (PostgreSQL) ---------- +[database] +DB_TYPE = postgres +HOST = 127.0.0.1:5432 +NAME = gitea +USER = gitea_user +PASSWD = SICHERES_PASSWORT_HIER +SSL_MODE = disable +LOG_SQL = false + +; ---------- Sicherheit ---------- +[security] +INSTALL_LOCK = true ; Installer deaktivieren +SECRET_KEY = ; Wird automatisch generiert +INTERNAL_TOKEN = ; Wird automatisch generiert +PASSWORD_COMPLEXITY = lower,upper,digit,spec +MIN_PASSWORD_LENGTH = 12 +PASSWORD_CHECK_PWN = true ; Prüfung gegen bekannte Leaks + +; ---------- Service ---------- +[service] +REGISTER_EMAIL_CONFIRM = true ; E-Mail-Bestätigung +DISABLE_REGISTRATION = false ; Registrierung erlauben +ALLOW_ONLY_EXTERNAL_REGISTRATION = false +REQUIRE_SIGNIN_VIEW = false ; Öffentliche Repos ohne Login sichtbar +DEFAULT_KEEP_EMAIL_PRIVATE = true +DEFAULT_ALLOW_CREATE_ORGANIZATION = true +NO_REPLY_ADDRESS = noreply.git.example.de +ENABLE_NOTIFY_MAIL = true + +; ---------- E-Mail (SMTP) ---------- +[mailer] +ENABLED = true +PROTOCOL = smtp+starttls +SMTP_ADDR = smtp.example.de +SMTP_PORT = 587 +USER = gitea@example.de +PASSWD = SMTP_PASSWORT_HIER +FROM = "Gitea" + +; ---------- Session ---------- +[session] +PROVIDER = file +PROVIDER_CONFIG = /var/lib/gitea/data/sessions +COOKIE_SECURE = true ; Nur über HTTPS + +; ---------- Cache ---------- +[cache] +ADAPTER = memory +INTERVAL = 60 + +; ---------- Logging ---------- +[log] +MODE = file +LEVEL = info +ROOT_PATH = /var/lib/gitea/log + +; ---------- Markup / Rendering ---------- +[markup.asciidoc] +ENABLED = true + +; ---------- Indexer (Volltextsuche) ---------- +[indexer] +ISSUE_INDEXER_TYPE = bleve +ISSUE_INDEXER_PATH = /var/lib/gitea/data/indexers/issues.bleve +REPO_INDEXER_ENABLED = true +REPO_INDEXER_PATH = /var/lib/gitea/data/indexers/repos.bleve +REPO_INDEXER_INCLUDE = +REPO_INDEXER_EXCLUDE = resources/bin/** +MAX_FILE_SIZE = 1048576 ; 1 MB + +; ---------- Webhook ---------- +[webhook] +ALLOWED_HOST_LIST = external,loopback ; Externe und lokale Webhooks +DELIVER_TIMEOUT = 10 + +; ---------- API ---------- +[api] +ENABLE_SWAGGER = true +MAX_RESPONSE_ITEMS = 50 + +; ---------- Aktionen (CI/CD) ---------- +[actions] +ENABLED = true +DEFAULT_ACTIONS_URL = https://github.com +``` + +### 3.2 Konfigurationsänderungen anwenden + +```bash +# Nach Änderungen an app.ini: Gitea neu starten +sudo systemctl restart gitea + +# Konfiguration prüfen (ohne Neustart) +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini +``` + +### 3.3 Konfigurationsreferenz + +Die vollständige Liste aller Optionen ist in der offiziellen Dokumentation zu finden: + +``` +https://docs.gitea.com/administration/config-cheat-sheet +``` + +--- + +## 4. PostgreSQL-Anbindung + +### 4.1 Datenbank und Benutzer erstellen + +Falls nicht bereits im Rahmen der PostgreSQL-Installation geschehen: + +```bash +# Als PostgreSQL-Superuser verbinden +sudo -u postgres psql +``` + +```sql +-- Benutzer erstellen +CREATE USER gitea_user WITH PASSWORD 'SICHERES_PASSWORT_HIER'; + +-- Datenbank erstellen +CREATE DATABASE gitea + OWNER gitea_user + ENCODING 'UTF8' + LC_COLLATE 'de_DE.UTF-8' + LC_CTYPE 'de_DE.UTF-8' + TEMPLATE template0; + +-- Berechtigungen vergeben +GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea_user; + +-- Schema-Berechtigungen +\c gitea +GRANT ALL ON SCHEMA public TO gitea_user; +``` + +### 4.2 Verbindung testen + +```bash +# Als gitea_user verbinden +psql -h 127.0.0.1 -U gitea_user -d gitea + +# In psql: Tabellen anzeigen (nach der Ersteinrichtung) +\dt +\q +``` + +### 4.3 pg_hba.conf prüfen + +Sicherstellen, dass der Zugriff für den Gitea-Benutzer konfiguriert ist: + +```bash +sudo cat /etc/postgresql/16/main/pg_hba.conf | grep -v "^#" | grep -v "^$" +``` + +Benötigter Eintrag: + +```conf +host gitea gitea_user 127.0.0.1/32 scram-sha-256 +``` + +### 4.4 Datenbankstatus prüfen + +```sql +-- Als postgres-Superuser: +-- Tabellenzahl prüfen (Gitea erstellt ca. 60+ Tabellen) +SELECT COUNT(*) FROM information_schema.tables +WHERE table_schema = 'public' AND table_catalog = 'gitea'; + +-- Datenbankgröße +SELECT pg_size_pretty(pg_database_size('gitea')); + +-- Größte Tabellen +SELECT tablename, + pg_size_pretty(pg_total_relation_size('public.' || tablename)) AS groesse +FROM pg_tables +WHERE schemaname = 'public' +ORDER BY pg_total_relation_size('public.' || tablename) DESC +LIMIT 10; +``` + +--- + +## 5. Reverse Proxy und SSL + +### 5.1 Nginx-Konfiguration + +```bash +sudo nano /etc/nginx/sites-available/gitea +``` + +```nginx +server { + listen 80; + server_name git.example.de; + return 301 https://$server_name$request_uri; +} + +server { + listen 443 ssl http2; + server_name git.example.de; + + # SSL-Zertifikate + ssl_certificate /etc/letsencrypt/live/git.example.de/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/git.example.de/privkey.pem; + + # Sicherheitsheader + add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-Frame-Options "SAMEORIGIN" always; + + # Maximale Upload-Größe (Git LFS, Anhänge) + client_max_body_size 512M; + + location / { + proxy_pass http://127.0.0.1:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket-Support (für Live-Features) + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + + # Timeouts für große Repositories + proxy_connect_timeout 300; + proxy_send_timeout 300; + proxy_read_timeout 300; + } +} +``` + +```bash +sudo ln -sf /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/ +sudo nginx -t +sudo systemctl reload nginx +``` + +### 5.2 Caddy-Konfiguration + +```caddyfile +git.example.de { + request_body { + max_size 512MB + } + + reverse_proxy 127.0.0.1:3000 { + header_up X-Real-IP {remote_host} + transport http { + read_timeout 300s + } + } +} +``` + +### 5.3 SSL-Zertifikat (Let's Encrypt) + +```bash +sudo apt install -y certbot python3-certbot-nginx +sudo certbot --nginx -d git.example.de +sudo certbot renew --dry-run +``` + +--- + +## 6. Benutzerverwaltung + +### 6.1 Administrator-Konto erstellen + +Falls kein Admin bei der Ersteinrichtung erstellt wurde: + +```bash +sudo -u gitea gitea admin user create \ + --config /etc/gitea/app.ini \ + --username admin \ + --password 'SICHERES_PASSWORT' \ + --email admin@example.de \ + --admin +``` + +### 6.2 Benutzer über die CLI verwalten + +```bash +# Alle Benutzer auflisten +sudo -u gitea gitea admin user list --config /etc/gitea/app.ini + +# Benutzer erstellen +sudo -u gitea gitea admin user create \ + --config /etc/gitea/app.ini \ + --username neuerbenutzer \ + --password 'Passwort123!' \ + --email benutzer@example.de + +# Passwort ändern +sudo -u gitea gitea admin user change-password \ + --config /etc/gitea/app.ini \ + --username neuerbenutzer \ + --password 'NeuesPasswort456!' + +# Admin-Rechte vergeben +sudo -u gitea gitea admin user change-password \ + --config /etc/gitea/app.ini \ + --username neuerbenutzer \ + --admin +``` + +### 6.3 Benutzer über die Weboberfläche verwalten + +1. Als Administrator anmelden +2. **Site-Administration** (Krone-Symbol oben rechts) → **Benutzerkonten** +3. Mögliche Aktionen: + +| Aktion | Beschreibung | +|---|---| +| Erstellen | Neuen Benutzer mit E-Mail und Passwort anlegen | +| Bearbeiten | Berechtigungen, E-Mail, Passwort ändern | +| Deaktivieren | Konto sperren, Daten bleiben erhalten | +| Löschen | Konto und alle zugehörigen Repositories entfernen | + +### 6.4 Zwei-Faktor-Authentifizierung (2FA) + +Jeder Benutzer kann 2FA selbst aktivieren: + +1. **Einstellungen** → **Sicherheit** → **Zwei-Faktor-Authentifizierung** +2. QR-Code mit einer TOTP-App scannen (Aegis, Authy etc.) +3. Bestätigungscode eingeben +4. **Wiederherstellungscodes** sicher aufbewahren + +2FA für alle Benutzer erzwingen (in `app.ini`): + +```ini +[service] +ENABLE_BASIC_AUTHENTICATION = false + +[auth.webauthn] +ENABLED = true + +[security] +MIN_PASSWORD_LENGTH = 12 +``` + +### 6.5 Externe Authentifizierung (OAuth2 / LDAP) + +Gitea unterstützt verschiedene externe Authentifizierungsquellen: + +1. **Site-Administration** → **Authentifizierungsquellen** → **Hinzufügen** +2. Unterstützte Typen: + +| Typ | Beschreibung | +|---|---| +| **LDAP** | Active Directory, OpenLDAP | +| **OAuth2** | GitHub, GitLab, Google, Keycloak etc. | +| **SMTP** | Authentifizierung über den E-Mail-Server | +| **PAM** | Linux-Systembenutzer | + +--- + +## 7. Repositories verwalten + +### 7.1 Repository über die Weboberfläche erstellen + +1. **„+"** → **Neues Repository** +2. Felder ausfüllen: + - **Besitzer:** Eigener Benutzer oder Organisation + - **Name:** Repository-Name (keine Leerzeichen) + - **Sichtbarkeit:** Öffentlich oder Privat + - **Beschreibung:** Optional + - **README initialisieren:** Empfohlen + - **.gitignore:** Vorlage passend zur Sprache + - **Lizenz:** Je nach Projekt +3. **Repository erstellen** + +### 7.2 Repository klonen + +```bash +# Über HTTPS +git clone https://git.example.de/benutzer/mein-repo.git + +# Über SSH +git clone git@git.example.de:benutzer/mein-repo.git +``` + +### 7.3 Bestehendes Projekt importieren + +```bash +# Lokales Projekt mit Gitea verbinden +cd /pfad/zum/projekt +git init +git add . +git commit -m "Erster Commit" +git remote add origin https://git.example.de/benutzer/mein-repo.git +git push -u origin main +``` + +### 7.4 Repository per Push erstellen + +Wenn in `app.ini` aktiviert (`ENABLE_PUSH_CREATE_USER = true`): + +```bash +# Erstellt das Repository automatisch beim ersten Push +git remote add origin git@git.example.de:benutzer/neues-repo.git +git push -u origin main +``` + +### 7.5 Repository migrieren (Import) + +Gitea kann Repositories von anderen Plattformen importieren: + +1. **„+"** → **Neue Migration** +2. Plattform wählen: GitHub, GitLab, Bitbucket, Gitea, Gogs etc. +3. URL des Quell-Repositories eingeben +4. Optionen: + - [x] Issues migrieren + - [x] Labels migrieren + - [x] Pull Requests migrieren + - [x] Releases migrieren + - [x] Wiki migrieren +5. **Repository migrieren** + +### 7.6 Repository-Einstellungen + +In den Repository-Einstellungen (Zahnrad-Symbol) können konfiguriert werden: + +| Einstellung | Beschreibung | +|---|---| +| **Allgemein** | Name, Beschreibung, Sichtbarkeit, Website | +| **Zusammenarbeit** | Benutzer und Teams mit Rechten hinzufügen | +| **Branches** | Branch-Schutzregeln, Standard-Branch | +| **Webhooks** | Ereignisbasierte HTTP-Callbacks | +| **Git Hooks** | Pre-receive, Post-receive, Update-Hooks | +| **Deploy Keys** | Schreibgeschützte oder volle SSH-Schlüssel | +| **Gefahrenzone** | Repository übertragen, archivieren, löschen | + +### 7.7 Repository-Berechtigungen + +| Berechtigung | Lesen | Schreiben | Admin | +|---|---|---|---| +| Code einsehen | ✅ | ✅ | ✅ | +| Klonen | ✅ | ✅ | ✅ | +| Pushen | ❌ | ✅ | ✅ | +| Issues erstellen | ✅ | ✅ | ✅ | +| Pull Requests mergen | ❌ | ✅ | ✅ | +| Einstellungen ändern | ❌ | ❌ | ✅ | +| Repository löschen | ❌ | ❌ | ✅ | + +--- + +## 8. Branches, Tags und Releases + +### 8.1 Branches + +```bash +# Neuen Branch erstellen +git checkout -b feature/neue-funktion + +# Branch pushen +git push -u origin feature/neue-funktion + +# Branches auflisten +git branch -a + +# Branch löschen (lokal und remote) +git branch -d feature/neue-funktion +git push origin --delete feature/neue-funktion +``` + +### 8.2 Branch-Schutzregeln + +Über die Weboberfläche unter **Repository-Einstellungen → Branches**: + +| Regel | Beschreibung | +|---|---| +| **Push deaktivieren** | Kein direkter Push auf den Branch (nur über PR) | +| **Merge-Whitelist** | Nur bestimmte Benutzer dürfen mergen | +| **Review erforderlich** | Mindestanzahl an Freigaben vor dem Merge | +| **Statusprüfungen** | CI/CD muss erfolgreich sein | +| **Force-Push blockieren** | Verhindert History-Umschreibung | +| **Branch löschen blockieren** | Schutz vor versehentlichem Löschen | + +Empfehlung für den `main`-Branch: + +- [x] Push deaktivieren +- [x] Mindestens 1 Review erforderlich +- [x] Force-Push blockieren +- [x] Branch löschen blockieren + +### 8.3 Tags und Releases + +```bash +# Tag erstellen und pushen +git tag -a v1.0.0 -m "Version 1.0.0" +git push origin v1.0.0 + +# Alle Tags auflisten +git tag -l +``` + +Release über die Weboberfläche: + +1. **Repository** → **Releases** → **Neues Release** +2. Tag auswählen oder neuen Tag erstellen +3. Release-Titel und Beschreibung (Changelog) +4. Optional: Binärdateien als Anhänge hochladen +5. **Release veröffentlichen** + +--- + +## 9. Issues und Projektplanung + +### 9.1 Issues erstellen + +1. **Repository** → **Issues** → **Neues Issue** +2. **Titel** und **Beschreibung** eingeben (Markdown wird unterstützt) +3. Optional: + - **Labels** zuweisen (z. B. Bug, Feature, Priorität) + - **Meilenstein** zuordnen + - **Verantwortlichen** zuweisen + - **Projekt** zuordnen + +### 9.2 Labels verwalten + +Labels helfen bei der Kategorisierung. Gitea bietet vordefinierte Label-Sets: + +1. **Repository** → **Labels** → **Label-Set verwenden** +2. Oder eigene Labels erstellen mit Name, Farbe und Beschreibung + +Empfohlene Labels: + +| Label | Farbe | Verwendung | +|---|---|---| +| `bug` | 🔴 Rot | Fehler | +| `feature` | 🟢 Grün | Neue Funktionen | +| `enhancement` | 🔵 Blau | Verbesserungen | +| `documentation` | 🟡 Gelb | Dokumentation | +| `priority: high` | 🟠 Orange | Hohe Priorität | +| `priority: low` | ⚪ Grau | Niedrige Priorität | +| `wontfix` | ⚫ Schwarz | Wird nicht behoben | + +### 9.3 Meilensteine + +Meilensteine fassen Issues zu einem Ziel zusammen (z. B. Version 2.0): + +1. **Issues** → **Meilensteine** → **Neuer Meilenstein** +2. Titel, Beschreibung und Fälligkeitsdatum festlegen +3. Issues dem Meilenstein zuweisen +4. Fortschritt wird automatisch berechnet + +### 9.4 Projekte (Kanban-Board) + +Gitea bietet integrierte Kanban-Boards: + +1. **Repository** oder **Organisation** → **Projekte** → **Neues Projekt** +2. Board-Typ wählen (Kanban oder Tabelle) +3. Spalten erstellen (z. B. „Offen", „In Arbeit", „Review", „Fertig") +4. Issues per Drag-and-Drop verschieben + +### 9.5 Referenzen in Commits + +Issues können direkt aus Commits referenziert und geschlossen werden: + +```bash +# Issue referenzieren +git commit -m "Login-Seite überarbeitet, siehe #42" + +# Issue automatisch schließen +git commit -m "Login-Bug behoben, closes #42" +git commit -m "Fix: Absturz bei leerem Passwort, fixes #15" +``` + +Schlüsselwörter zum Schließen: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved` + +--- + +## 10. Pull Requests und Code-Review + +### 10.1 Pull Request erstellen + +1. Änderungen in einem Feature-Branch committen und pushen +2. In Gitea: **Neuer Pull Request** +3. **Quell-Branch** → **Ziel-Branch** (z. B. `feature/login` → `main`) +4. Titel und Beschreibung ausfüllen +5. Reviewer, Labels und Meilenstein zuweisen +6. **Pull Request erstellen** + +### 10.2 Code-Review durchführen + +Als Reviewer: + +1. Pull Request öffnen → **Geänderte Dateien** +2. Zeilen kommentieren (auf das „+" neben der Zeilennummer klicken) +3. Review abschließen: + +| Option | Beschreibung | +|---|---| +| **Kommentar** | Feedback ohne Freigabe/Ablehnung | +| **Freigabe** | Code ist in Ordnung, kann gemergt werden | +| **Änderungen angefordert** | Nachbesserung nötig | + +### 10.3 Merge-Strategien + +Gitea unterstützt verschiedene Merge-Methoden: + +| Methode | Beschreibung | Ergebnis | +|---|---|---| +| **Merge Commit** | Erstellt einen Merge-Commit | Vollständige History, klar erkennbar | +| **Rebase** | Commits werden auf den Ziel-Branch umbasiert | Lineare History | +| **Squash** | Alle Commits werden zu einem zusammengefasst | Saubere History | +| **Rebase Merge** | Rebase + Merge-Commit | Kombination | + +Die verfügbaren Methoden können pro Repository oder global konfiguriert werden: + +```ini +; In app.ini +[repository.pull-request] +DEFAULT_MERGE_STYLE = merge +WORK_IN_PROGRESS_PREFIXES = WIP:,[WIP] +``` + +### 10.4 Automatische PR-Checks + +Pull Requests können automatische Prüfungen erfordern: + +- **CI/CD-Status** (Gitea Actions müssen erfolgreich sein) +- **Review-Freigaben** (mindestens X Freigaben) +- **Keine Konflikte** (Branch muss aktuell sein) + +--- + +## 11. CI/CD mit Gitea Actions + +### 11.1 Überblick + +Gitea Actions ist ein integriertes CI/CD-System, das mit GitHub Actions kompatibel ist. Workflows werden in YAML-Dateien definiert und bei bestimmten Ereignissen ausgelöst. + +### 11.2 Gitea Actions aktivieren + +In `app.ini` (bereits in der Standardkonfiguration enthalten): + +```ini +[actions] +ENABLED = true +DEFAULT_ACTIONS_URL = https://github.com +``` + +### 11.3 Runner registrieren + +Gitea Actions benötigt einen separaten Runner, der die Workflows ausführt: + +```bash +# act_runner herunterladen +RUNNER_VERSION="0.2.11" +wget -O /usr/local/bin/act_runner \ + "https://dl.gitea.com/act_runner/${RUNNER_VERSION}/act_runner-${RUNNER_VERSION}-linux-amd64" +chmod +x /usr/local/bin/act_runner + +# Runner registrieren (Token aus der Weboberfläche holen) +# Site-Administration → Runner → Registrierungstoken erstellen +act_runner register \ + --instance https://git.example.de \ + --token RUNNER_TOKEN_HIER \ + --name "server-runner" \ + --labels "ubuntu-latest:docker://node:20,self-hosted:host" + +# Runner als Systemd-Service +sudo nano /etc/systemd/system/gitea-runner.service +``` + +```ini +[Unit] +Description=Gitea Actions Runner +After=network.target gitea.service + +[Service] +Type=simple +User=gitea +WorkingDirectory=/var/lib/gitea +ExecStart=/usr/local/bin/act_runner daemon --config /var/lib/gitea/.runner +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target +``` + +```bash +sudo systemctl daemon-reload +sudo systemctl enable gitea-runner +sudo systemctl start gitea-runner +``` + +### 11.4 Workflow-Datei erstellen + +Workflow-Dateien liegen im Repository unter `.gitea/workflows/`: + +```yaml +# .gitea/workflows/ci.yaml +name: CI Pipeline + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Code auschecken + uses: actions/checkout@v4 + + - name: Node.js einrichten + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Abhängigkeiten installieren + run: npm ci + + - name: Tests ausführen + run: npm test + + - name: Linting + run: npm run lint + + build: + runs-on: ubuntu-latest + needs: test + steps: + - uses: actions/checkout@v4 + - run: npm ci + - run: npm run build +``` + +### 11.5 Secrets verwalten + +Secrets werden in der Weboberfläche konfiguriert: + +1. **Repository** → **Einstellungen** → **Actions** → **Secrets** +2. **Neues Secret:** Name und Wert eingeben +3. Im Workflow verwenden: + +```yaml +env: + API_KEY: ${{ secrets.API_KEY }} +``` + +--- + +## 12. Wiki-Funktion und Wiki.js-Anbindung + +### 12.1 Integriertes Gitea-Wiki + +Jedes Repository hat ein integriertes Wiki: + +1. **Repository** → **Wiki** → **Neue Seite** +2. Inhalt in Markdown schreiben +3. **Speichern** + +Das Wiki ist ein eigenes Git-Repository und kann auch lokal bearbeitet werden: + +```bash +# Wiki-Repository klonen +git clone https://git.example.de/benutzer/mein-repo.wiki.git + +# Seiten bearbeiten (Markdown-Dateien) +cd mein-repo.wiki +nano Startseite.md + +# Änderungen pushen +git add . +git commit -m "Wiki aktualisiert" +git push +``` + +### 12.2 Wiki.js mit Gitea verbinden + +Wiki.js kann ein Gitea-Repository als Speicher-Backend nutzen. So werden alle Wiki-Inhalte versioniert in Git gespeichert. + +#### Schritt 1: Repository für Wiki.js erstellen + +In Gitea ein neues Repository erstellen: +- **Name:** `wiki-content` (oder beliebig) +- **Sichtbarkeit:** Privat (empfohlen) +- **README initialisieren:** Ja + +#### Schritt 2: Deploy Key oder Access Token erstellen + +**Variante A: Access Token (empfohlen)** + +1. In Gitea: **Benutzer-Einstellungen** → **Anwendungen** → **Zugriffstoken erstellen** +2. Name: `wiki-js-sync` +3. Berechtigungen: `repo` (Lesen/Schreiben) +4. Token kopieren und sicher aufbewahren + +**Variante B: Deploy Key** + +```bash +# SSH-Schlüssel auf dem Server generieren +sudo -u wiki ssh-keygen -t ed25519 -C "wiki-js" -f /home/wiki/.ssh/gitea_deploy +``` + +1. Repository → **Einstellungen** → **Deploy-Schlüssel** → **Hinzufügen** +2. Öffentlichen Schlüssel einfügen +3. **Schreibzugriff** aktivieren + +#### Schritt 3: Wiki.js Git-Speicher konfigurieren + +1. In Wiki.js: **Administration** → **Speicher** → **Git** +2. Konfiguration: + +| Feld | Wert | +|---|---| +| Authentifizierungstyp | `basic` (für Token) oder `ssh` (für Deploy Key) | +| Repository-URL | `https://git.example.de/benutzer/wiki-content.git` | +| Branch | `main` | +| Benutzername | `wiki-js-sync` (oder der Gitea-Benutzername) | +| Passwort / Token | Der erstellte Access Token | +| Autoren-E-Mail | `wiki@example.de` | +| Autoren-Name | `Wiki.js` | +| SSL verifizieren | `Ja` (bei gültigem Zertifikat) | + +3. **Synchronisierungsintervall:** `5 Minuten` (oder nach Bedarf) +4. **Speichern** und **Aktivieren** + +#### Schritt 4: Synchronisierung prüfen + +```bash +# Im Gitea-Repository sollten nach der ersten Synchronisierung Dateien erscheinen +# Jede Wiki-Seite wird als Markdown-Datei gespeichert + +# Manuell prüfen: +cd /tmp +git clone https://git.example.de/benutzer/wiki-content.git +ls wiki-content/ +``` + +#### Vorteile der Git-Anbindung + +| Vorteil | Beschreibung | +|---|---| +| **Versionierung** | Jede Änderung wird als Git-Commit gespeichert | +| **Backup** | Wiki-Inhalte sind im Git-Repository gesichert | +| **Offline-Bearbeitung** | Inhalte können lokal bearbeitet und gepusht werden | +| **Mehrere Editoren** | Bearbeitung sowohl in Wiki.js als auch direkt in Git | +| **Review-Prozess** | Änderungen können über Pull Requests geprüft werden | + +--- + +## 13. SSH-Zugang und Authentifizierung + +### 13.1 SSH-Schlüssel hinzufügen + +Jeder Benutzer kann SSH-Schlüssel in seinem Profil hinterlegen: + +1. SSH-Schlüssel lokal erstellen (falls nicht vorhanden): + +```bash +ssh-keygen -t ed25519 -C "benutzer@example.de" +cat ~/.ssh/id_ed25519.pub +``` + +2. In Gitea: **Einstellungen** → **SSH/GPG-Schlüssel** → **Schlüssel hinzufügen** +3. Öffentlichen Schlüssel einfügen und speichern + +### 13.2 SSH-Verbindung testen + +```bash +ssh -T git@git.example.de +# Erwartete Ausgabe: Hi benutzer! You've successfully authenticated... +``` + +### 13.3 SSH-Konfiguration (Client-Seite) + +Bei nicht standardmäßigem Port oder mehreren Schlüsseln: + +```bash +nano ~/.ssh/config +``` + +``` +Host git.example.de + HostName git.example.de + Port 22 + User git + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes +``` + +### 13.4 GPG-Signierung + +Commits können mit GPG signiert werden: + +```bash +# GPG-Schlüssel erstellen +gpg --full-generate-key + +# Öffentlichen Schlüssel exportieren +gpg --armor --export SCHLUESSEL_ID + +# In Gitea: Einstellungen → SSH/GPG-Schlüssel → GPG-Schlüssel hinzufügen + +# Git für Signierung konfigurieren +git config --global user.signingkey SCHLUESSEL_ID +git config --global commit.gpgsign true +``` + +Signierte Commits werden in Gitea mit einem grünen „Verifiziert"-Badge angezeigt. + +--- + +## 14. Webhooks und Integrationen + +### 14.1 Webhook erstellen + +1. **Repository** → **Einstellungen** → **Webhooks** → **Webhook hinzufügen** +2. Webhook-Typ wählen: + +| Typ | Beschreibung | +|---|---| +| **Gitea** | Standard-JSON-Format | +| **Slack** | Slack-kompatibles Format | +| **Discord** | Discord-kompatibles Format | +| **Telegram** | Telegram-Bot-Format | +| **Microsoft Teams** | Teams-kompatibles Format | +| **Feishu / DingTalk** | Chinesische Messenger | +| **Matrix** | Matrix-kompatibles Format | +| **Paketdienst** | Allgemeines JSON | + +3. **Ziel-URL** eingeben +4. **Ereignisse** auswählen (Push, Pull Request, Issue etc.) +5. **Secret** festlegen (zur Verifizierung) +6. **Webhook hinzufügen** + +### 14.2 Beispiel: Webhook an n8n + +n8n kann Gitea-Webhooks empfangen und daraufhin Workflows auslösen: + +1. In n8n: **Webhook-Node** erstellen → URL kopieren +2. In Gitea: Webhook mit der n8n-URL erstellen +3. Ereignisse wählen (z. B. Push, Pull Request) + +Typische Automatisierungen: +- Bei Push: Automatisches Deployment auslösen +- Bei neuem Issue: Benachrichtigung in Slack/Teams +- Bei Pull Request: Automatische Code-Analyse starten + +### 14.3 Webhook-Zustellung prüfen + +In Gitea unter **Repository → Einstellungen → Webhooks → (Webhook auswählen)** können vergangene Zustellungen eingesehen werden, einschließlich Request/Response-Daten. + +--- + +## 15. Pakete und Container Registry + +### 15.1 Überblick + +Gitea bietet eine integrierte Paket-Registry für verschiedene Formate: + +| Format | Befehl | Anwendung | +|---|---|---| +| **Docker** | `docker push/pull` | Container-Images | +| **npm** | `npm publish` | JavaScript-Pakete | +| **PyPI** | `pip install` / `twine upload` | Python-Pakete | +| **Maven** | `mvn deploy` | Java-Pakete | +| **NuGet** | `dotnet nuget push` | .NET-Pakete | +| **Cargo** | `cargo publish` | Rust-Pakete | +| **Composer** | `composer require` | PHP-Pakete | +| **Generic** | HTTP Upload | Beliebige Dateien | + +### 15.2 Docker-Registry verwenden + +```bash +# Anmelden +docker login git.example.de + +# Image taggen +docker tag mein-image:latest git.example.de/benutzer/mein-image:latest + +# Image pushen +docker push git.example.de/benutzer/mein-image:latest + +# Image pullen +docker pull git.example.de/benutzer/mein-image:latest +``` + +### 15.3 npm-Registry verwenden + +```bash +# .npmrc konfigurieren +echo "@scope:registry=https://git.example.de/api/packages/benutzer/npm/ +//git.example.de/api/packages/benutzer/npm/:_authToken=DEIN_TOKEN" > .npmrc + +# Paket veröffentlichen +npm publish +``` + +### 15.4 Generic-Pakete (beliebige Dateien) + +```bash +# Datei hochladen +curl -X PUT \ + -H "Authorization: token DEIN_TOKEN" \ + --upload-file ./build.zip \ + "https://git.example.de/api/packages/benutzer/generic/mein-paket/1.0.0/build.zip" + +# Datei herunterladen +curl -o build.zip \ + "https://git.example.de/api/packages/benutzer/generic/mein-paket/1.0.0/build.zip" +``` + +--- + +## 16. Datensicherung und Wiederherstellung + +### 16.1 Was wird gesichert? + +| Komponente | Speicherort | Methode | +|---|---|---| +| **PostgreSQL-Datenbank** | PostgreSQL | `pg_dump` | +| **Git-Repositories** | `/var/lib/gitea/repositories` | Dateisystem | +| **LFS-Daten** | `/var/lib/gitea/data/lfs` | Dateisystem | +| **Anhänge** | `/var/lib/gitea/data/attachments` | Dateisystem | +| **Avatare** | `/var/lib/gitea/data/avatars` | Dateisystem | +| **Konfiguration** | `/etc/gitea/app.ini` | Dateisystem | +| **Log-Dateien** | `/var/lib/gitea/log` | Optional | + +### 16.2 Gitea-internes Backup (gitea dump) + +Gitea bietet einen eingebauten Backup-Befehl: + +```bash +# Vollständiges Backup erstellen +sudo -u gitea gitea dump \ + --config /etc/gitea/app.ini \ + --type tar.gz \ + --file /backup/gitea/gitea-dump-$(date +%Y%m%d).tar.gz +``` + +Der Dump enthält: +- Datenbank-Export (SQL) +- Repositories +- Konfiguration +- Log-Dateien (optional) + +### 16.3 Manuelles Backup (empfohlen) + +Für mehr Kontrolle: + +```bash +#!/bin/bash +# /opt/scripts/gitea-backup.sh + +set -e + +TIMESTAMP=$(date +%Y%m%d_%H%M%S) +BACKUP_DIR="/backup/gitea" +KEEP_DAYS=30 + +mkdir -p "$BACKUP_DIR" + +echo "[$(date)] Gitea-Backup gestartet..." + +# 1. PostgreSQL-Datenbank sichern +sudo -u postgres pg_dump -Fc gitea > "${BACKUP_DIR}/db_${TIMESTAMP}.dump" + +# 2. Repositories sichern +tar -czf "${BACKUP_DIR}/repos_${TIMESTAMP}.tar.gz" \ + -C /var/lib/gitea repositories/ + +# 3. Daten sichern (LFS, Anhänge, Avatare etc.) +tar -czf "${BACKUP_DIR}/data_${TIMESTAMP}.tar.gz" \ + -C /var/lib/gitea/data \ + lfs/ attachments/ avatars/ 2>/dev/null || true + +# 4. Konfiguration sichern +cp /etc/gitea/app.ini "${BACKUP_DIR}/app.ini_${TIMESTAMP}" + +# 5. Alte Backups löschen +find "$BACKUP_DIR" -name "*.dump" -mtime +$KEEP_DAYS -delete +find "$BACKUP_DIR" -name "*.tar.gz" -mtime +$KEEP_DAYS -delete +find "$BACKUP_DIR" -name "app.ini_*" -mtime +$KEEP_DAYS -delete + +echo "[$(date)] Gitea-Backup abgeschlossen." +``` + +```bash +sudo chmod +x /opt/scripts/gitea-backup.sh +``` + +### 16.4 Automatisches Backup (Cronjob) + +```bash +sudo nano /etc/cron.d/gitea-backup +``` + +```cron +# Tägliches Backup um 02:30 Uhr +30 2 * * * root /opt/scripts/gitea-backup.sh >> /var/log/gitea-backup.log 2>&1 +``` + +### 16.5 Wiederherstellung + +```bash +# 1. Gitea stoppen +sudo systemctl stop gitea + +# 2. Datenbank wiederherstellen +sudo -u postgres dropdb gitea +sudo -u postgres createdb -O gitea_user gitea +sudo -u postgres pg_restore -d gitea /backup/gitea/db_YYYYMMDD_HHMMSS.dump + +# 3. Repositories wiederherstellen +sudo tar -xzf /backup/gitea/repos_YYYYMMDD_HHMMSS.tar.gz \ + -C /var/lib/gitea/ + +# 4. Daten wiederherstellen +sudo tar -xzf /backup/gitea/data_YYYYMMDD_HHMMSS.tar.gz \ + -C /var/lib/gitea/data/ + +# 5. Konfiguration wiederherstellen +sudo cp /backup/gitea/app.ini_YYYYMMDD_HHMMSS /etc/gitea/app.ini + +# 6. Berechtigungen setzen +sudo chown -R gitea:gitea /var/lib/gitea +sudo chmod 640 /etc/gitea/app.ini + +# 7. Gitea starten +sudo systemctl start gitea + +# 8. Git-Repositories regenerieren (falls nötig) +sudo -u gitea gitea admin repo-sync-releases --config /etc/gitea/app.ini +``` + +--- + +## 17. Wartung und Updates + +### 17.1 Gitea aktualisieren + +```bash +# 1. Aktuelle Version prüfen +gitea --version + +# 2. Backup erstellen (siehe Abschnitt 16) +/opt/scripts/gitea-backup.sh + +# 3. Gitea stoppen +sudo systemctl stop gitea + +# 4. Neue Version herunterladen +GITEA_VERSION="1.22.6" # Durch aktuelle Version ersetzen +sudo wget -O /usr/local/bin/gitea \ + "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64" +sudo chmod +x /usr/local/bin/gitea + +# 5. Gitea starten (Datenbank-Migration erfolgt automatisch) +sudo systemctl start gitea + +# 6. Logs prüfen +sudo journalctl -u gitea --no-pager -n 50 + +# 7. Version bestätigen +gitea --version +``` + +> **Wichtig:** Immer die Release Notes lesen, bevor ein Update durchgeführt wird. Manche Versionen erfordern manuelle Migrationsschritte. + +### 17.2 Gesundheitscheck (Doctor) + +Gitea hat ein eingebautes Diagnose-Tool: + +```bash +# Vollständigen Check durchführen +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini + +# Nur bestimmte Checks +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini --run check-db-consistency + +# Automatische Reparatur +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini --fix +``` + +Verfügbare Checks: + +| Check | Beschreibung | +|---|---| +| `check-db-consistency` | Datenbank-Konsistenz prüfen | +| `check-repo-stats` | Repository-Statistiken aktualisieren | +| `check-db-collation` | Datenbank-Zeichensatz prüfen | + +### 17.3 Git-Repositories optimieren + +```bash +# Alle Repositories aufräumen (git gc) +sudo -u gitea gitea admin repo-sync-releases --config /etc/gitea/app.ini + +# Einzelnes Repository manuell optimieren +cd /var/lib/gitea/repositories/benutzer/repo.git +sudo -u gitea git gc --aggressive --prune=now +``` + +### 17.4 Suchindex neu aufbauen + +```bash +# Issue-Index neu aufbauen +sudo -u gitea gitea admin regenerate hooks --config /etc/gitea/app.ini + +# Code-Index neu aufbauen (bei aktiviertem Repo-Indexer) +# Indexer-Verzeichnis leeren und Gitea neu starten +sudo systemctl stop gitea +sudo rm -rf /var/lib/gitea/data/indexers/repos.bleve +sudo systemctl start gitea +``` + +### 17.5 Logdateien verwalten + +```bash +# Aktuelle Logs anzeigen +sudo tail -f /var/lib/gitea/log/gitea.log + +# Systemd-Journal +sudo journalctl -u gitea -f + +# Logrotate konfigurieren +sudo nano /etc/logrotate.d/gitea +``` + +``` +/var/lib/gitea/log/*.log { + daily + rotate 14 + compress + delaycompress + missingok + notifempty + copytruncate +} +``` + +--- + +## 18. Sicherheitshärtung + +### 18.1 Checkliste + +- [ ] **Installer gesperrt** (`INSTALL_LOCK = true` in `app.ini`) +- [ ] **HTTPS erzwungen** (Reverse Proxy mit SSL) +- [ ] **Offene Registrierung deaktiviert** (oder Domain-Whitelist) +- [ ] **Starke Passwort-Richtlinien** (`MIN_PASSWORD_LENGTH`, `PASSWORD_COMPLEXITY`) +- [ ] **2FA aktiviert** (mindestens für Administratoren) +- [ ] **SSH-Schlüssel statt Passwörter** für Git-Zugriff +- [ ] **Branch-Schutzregeln** auf `main`-Branch +- [ ] **Regelmäßige Backups** konfiguriert und getestet +- [ ] **Gitea aktuell halten** (Sicherheitsupdates) +- [ ] **Firewall konfiguriert** (nur Ports 22, 80, 443 öffentlich) +- [ ] **Admin-Bereich geschützt** (starkes Passwort, 2FA) +- [ ] **Cookie-Sicherheit** (`COOKIE_SECURE = true`) +- [ ] **Passwort-Leak-Prüfung** (`PASSWORD_CHECK_PWN = true`) + +### 18.2 Sicherheitsrelevante app.ini-Einstellungen + +```ini +[security] +INSTALL_LOCK = true +MIN_PASSWORD_LENGTH = 12 +PASSWORD_COMPLEXITY = lower,upper,digit,spec +PASSWORD_CHECK_PWN = true +SECRET_KEY = AUTOMATISCH_GENERIERT + +[service] +DISABLE_REGISTRATION = true +REGISTER_EMAIL_CONFIRM = true +REQUIRE_SIGNIN_VIEW = false +DEFAULT_KEEP_EMAIL_PRIVATE = true +ENABLE_CAPTCHA = true + +[session] +COOKIE_SECURE = true +COOKIE_NAME = gitea_session +SAME_SITE = strict + +[server] +LANDING_PAGE = explore +``` + +### 18.3 Fail2Ban für Gitea + +```bash +sudo nano /etc/fail2ban/filter.d/gitea.conf +``` + +```ini +[Definition] +failregex = .*Failed authentication attempt for .* from +ignoreregex = +``` + +```bash +sudo nano /etc/fail2ban/jail.d/gitea.local +``` + +```ini +[gitea] +enabled = true +port = http,https +filter = gitea +logpath = /var/lib/gitea/log/gitea.log +maxretry = 5 +bantime = 3600 +findtime = 600 +``` + +```bash +sudo systemctl restart fail2ban +``` + +### 18.4 Rate Limiting + +In `app.ini`: + +```ini +[api] +MAX_RESPONSE_ITEMS = 50 + +[service] +ENABLE_CAPTCHA = true +CAPTCHA_TYPE = image +``` + +--- + +## 19. Fehlerbehebung + +### 19.1 Gitea startet nicht + +```bash +# Service-Status prüfen +sudo systemctl status gitea + +# Ausführliche Logs +sudo journalctl -u gitea --no-pager -n 100 + +# Konfiguration prüfen +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini + +# Häufige Ursachen: +# - Datenbankverbindung fehlgeschlagen → PostgreSQL-Status prüfen +# - Port bereits belegt → sudo ss -tlnp | grep 3000 +# - Berechtigungsfehler → sudo chown -R gitea:gitea /var/lib/gitea +``` + +### 19.2 Datenbankverbindungsfehler + +```bash +# PostgreSQL-Status prüfen +sudo systemctl status postgresql + +# Verbindung manuell testen +psql -h 127.0.0.1 -U gitea_user -d gitea + +# Häufige Ursachen: +# - Falsches Passwort in app.ini +# - pg_hba.conf erlaubt die Verbindung nicht +# - PostgreSQL hört nicht auf localhost +``` + +### 19.3 Git Push / Pull schlägt fehl + +| Problem | Lösung | +|---|---| +| `Permission denied (publickey)` | SSH-Schlüssel in Gitea hinterlegen | +| `fatal: repository not found` | URL prüfen, Zugriffsrechte prüfen | +| `remote: error: pack exceeds maximum allowed size` | `client_max_body_size` in Nginx erhöhen | +| `error: RPC failed; HTTP 413` | Upload-Limit im Reverse Proxy erhöhen | +| `fatal: early EOF` | Netzwerkproblem, HTTP-Puffer vergrößern | + +Nginx HTTP-Puffer vergrößern: + +```nginx +# In der server-Konfiguration +proxy_buffering off; +proxy_request_buffering off; +client_max_body_size 1G; +``` + +### 19.4 Speicherplatz knapp + +```bash +# Gitea-Datenverbrauch prüfen +sudo du -sh /var/lib/gitea/repositories/ +sudo du -sh /var/lib/gitea/data/ +sudo du -sh /var/lib/gitea/log/ + +# Datenbank-Größe +sudo -u postgres psql -c "SELECT pg_size_pretty(pg_database_size('gitea'));" + +# Git-Repositories aufräumen +cd /var/lib/gitea/repositories/benutzer/repo.git +sudo -u gitea git gc --aggressive --prune=now + +# Alte Logs löschen +sudo find /var/lib/gitea/log -name "*.log" -mtime +30 -delete +``` + +### 19.5 Wiki.js-Synchronisierung funktioniert nicht + +```bash +# Git-Zugang prüfen +sudo -u wiki git ls-remote https://git.example.de/benutzer/wiki-content.git + +# Häufige Ursachen: +# - Token abgelaufen → Neuen Token erstellen +# - Repository umbenannt → URL in Wiki.js aktualisieren +# - Netzwerkfehler → DNS und Firewall prüfen +# - SSL-Fehler → Zertifikat prüfen + +# Wiki.js-Logs prüfen +sudo journalctl -u wiki-js --no-pager -n 50 +``` + +### 19.6 E-Mail-Versand funktioniert nicht + +```bash +# SMTP-Konfiguration in app.ini prüfen +grep -A 10 "\[mailer\]" /etc/gitea/app.ini + +# Test-E-Mail über die API senden +curl -X POST "https://git.example.de/api/v1/admin/sendmail" \ + -H "Authorization: token ADMIN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"subject":"Test","text":"Testmail","to":["admin@example.de"]}' + +# Gitea-Logs auf SMTP-Fehler prüfen +grep -i "mail\|smtp" /var/lib/gitea/log/gitea.log | tail -20 +``` + +--- + +## 20. Schnellreferenz – Befehle auf einen Blick + +### Systemd-Dienstverwaltung + +```bash +sudo systemctl start gitea # Starten +sudo systemctl stop gitea # Stoppen +sudo systemctl restart gitea # Neustarten +sudo systemctl status gitea # Status prüfen +sudo systemctl enable gitea # Autostart aktivieren +sudo journalctl -u gitea -f # Live-Logs +``` + +### Gitea-Administration (CLI) + +```bash +# Benutzer +sudo -u gitea gitea admin user list --config /etc/gitea/app.ini +sudo -u gitea gitea admin user create --config /etc/gitea/app.ini \ + --username NAME --password PASS --email MAIL +sudo -u gitea gitea admin user change-password --config /etc/gitea/app.ini \ + --username NAME --password NEUES_PASS + +# Diagnose +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini +sudo -u gitea gitea doctor check --config /etc/gitea/app.ini --fix + +# Backup +sudo -u gitea gitea dump --config /etc/gitea/app.ini \ + --type tar.gz --file /backup/gitea-dump.tar.gz + +# Regenerieren +sudo -u gitea gitea admin regenerate hooks --config /etc/gitea/app.ini +sudo -u gitea gitea admin repo-sync-releases --config /etc/gitea/app.ini +``` + +### Häufige Git-Befehle + +```bash +# Klonen +git clone git@git.example.de:benutzer/repo.git +git clone https://git.example.de/benutzer/repo.git + +# Täglicher Workflow +git pull # Aktuelle Änderungen holen +git checkout -b feature/xyz # Feature-Branch erstellen +git add . # Änderungen stagen +git commit -m "Beschreibung" # Committen +git push -u origin feature/xyz # Pushen + +# Nützlich +git status # Aktueller Status +git log --oneline -20 # Letzte 20 Commits +git diff # Änderungen anzeigen +git stash # Änderungen zwischenspeichern +git stash pop # Zwischengespeichertes wiederherstellen +``` + +### Gitea-API (Beispiele) + +```bash +# Token: Einstellungen → Anwendungen → Zugriffstoken + +# Repositories auflisten +curl -s -H "Authorization: token DEIN_TOKEN" \ + "https://git.example.de/api/v1/user/repos" | jq '.[].full_name' + +# Neues Repository erstellen +curl -X POST -H "Authorization: token DEIN_TOKEN" \ + -H "Content-Type: application/json" \ + "https://git.example.de/api/v1/user/repos" \ + -d '{"name":"neues-repo","private":false,"auto_init":true}' + +# Issues auflisten +curl -s -H "Authorization: token DEIN_TOKEN" \ + "https://git.example.de/api/v1/repos/benutzer/repo/issues" | jq '.[].title' +``` + +### Wichtige Dateipfade + +``` +/usr/local/bin/gitea # Gitea-Binärdatei +/etc/gitea/app.ini # Hauptkonfiguration +/var/lib/gitea/ # Arbeitsverzeichnis +├── repositories/ # Git-Repositories +├── data/ +│ ├── lfs/ # Git LFS-Objekte +│ ├── attachments/ # Issue-/Release-Anhänge +│ ├── avatars/ # Benutzer-Avatare +│ ├── sessions/ # Sitzungsdaten +│ ├── indexers/ # Suchindizes +│ └── packages/ # Paket-Registry-Daten +├── custom/ # Eigene Templates/Logos +└── log/ # Logdateien +/home/gitea/ # Home-Verzeichnis des Systembenutzers +└── .ssh/ # SSH-Schlüssel (authorized_keys) +``` + +### Wichtige URLs + +``` +Weboberfläche: https://git.example.de +API-Dokumentation: https://git.example.de/api/swagger +Admin-Bereich: https://git.example.de/-/admin +Benutzer-Settings: https://git.example.de/user/settings +``` + +--- + +> **Letzte Aktualisierung:** *24.02.2026* +> **Autor:** *Administrator* +> **Version:** 1.0