---
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" <gitea@example.de>

; ---------- 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 <HOST>
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