Gitea 2026 selbst hosten: Repositories, SSH und sichere Upgrades

Wenn Sie bereits versucht haben, Gitea selbst zu hosten, kommt Ihnen dieser frustrierende Zustand vermutlich bekannt vor: Die Benutzeroberfläche ist erreichbar, aber ROOT_URL erzeugt localhost-Clone-Links oder der SSH-Port wird nicht weitergeleitet. Das erneute Erstellen des Containers behebt nur selten einen Widerspruch zwischen URLs, Zustand und Abhängigkeiten.

Dieser Leitfaden verwendet ein konkretes Abschlusskriterium: per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen. Jede Konfigurationsentscheidung wird an diesem Kriterium gemessen und nicht an einem grünen Container-Status.

Jeden persistenten Byte in Gitea finden

Listen Sie den Zustand auf, bevor der erste echte Datensatz erstellt wird: Repositories, LFS-Objekte, Anhänge, Konfiguration und Datenbank. Mounten Sie /data vor dem Bootstrap, schreiben Sie harmlose Beispieldaten und ersetzen Sie den Container, um zu beweisen, dass dieser Pfad tatsächlich persistent ist. Bestätigen Sie den Mount, indem Sie harmlose Daten schreiben, Gitea ersetzen und die Daten wieder auslesen.

Snapshots sind für ein schnelles Rollback wertvoll. Wenn der Host oder das Volume verloren geht, ist jedoch ein unabhängiges Backup erforderlich. Stellen Sie die Daten in einer leeren Umgebung mit dem angepinnten Image wieder her und überprüfen Sie, dass die Repositories fsck bestehen, LFS-Objekte heruntergeladen werden können und Issues, Releases sowie Benutzerberechtigungen dem Zustand vor dem Backup entsprechen. Verwenden Sie persistente Volumes und Snapshots, um diese beiden Wiederherstellungsmechanismen klar voneinander zu trennen.

Einen austauschbaren Gitea-Container erstellen

Der folgende Befehl macht die Container-Grenze sichtbar, ohne so zu tun, als würden damit alle externen Services bereitgestellt.

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__security__SECRET_KEY=replace-with-a-long-random-value \
  gitea/gitea:latest

Überprüfen Sie vor dem Öffnen des Ingress die aufgelöste Umgebung, die Mounts und den Listener. Ergänzen Sie für eine stärker ausgelastete Installation die geprüften Verbindungseinstellungen für Postgres oder MySQL sowie bei Bedarf eine SSH-Route; verwenden Sie für private Services private Namen. Ein erfolgreicher Start ist erst erreicht, wenn Sie per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen können – nicht schon dann, wenn docker ps den Status Up ausgibt.

Gitea von seinen Abhängigkeiten trennen

Prozessgesundheit und Produktgesundheit sind bei Gitea zwei verschiedene Dinge. Port 3000 kann antworten, während die eigentliche Transaktion für Benutzer weiterhin fehlschlägt. Der Netzwerkvertrag für Gitea umfasst Postgres oder MySQL für eine stärker ausgelastete Installation sowie bei Bedarf eine SSH-Route. Halten Sie private Endpunkte im internen DNS, erlauben Sie nur erforderliche ausgehende Verbindungen und geben Sie Gitea ein Service-Credential mit eingeschränktem Berechtigungsumfang.

Führen Sie diese Readiness-Übung nach wesentlichen Konfigurationsänderungen aus: per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen. Halten Sie aufwendige externe Prüfungen aus den Liveness-Probes heraus, damit ein Ausfall eines Providers keine Restart-Schleife verursacht. Bei der Kapazitätsplanung sollten Sie Repository-Anzahl, Git-Object-Packing, LFS-Speicher, Datenbanklatenz und Runner-Auslastung verfolgen statt gewöhnlicher Seitenaufrufe. Das entspricht dem tatsächlichen Druck auf Gitea besser als Seitenaufrufe.

TLS ist einfach – generierte URLs sind es nicht

Veröffentlichen Sie Gitea unter einem einzigen HTTPS-Hostnamen und halten Sie den direkten Port 3000 privat. Setzen Sie ROOT_URL und SSH_DOMAIN auf die Adressen, unter denen Benutzer tatsächlich klonen. Dadurch wird verhindert, dass Browser und API-Clients zwei konkurrierende Adressen kennenlernen.

Führen Sie auf einem sauberen Client die bekannte funktionierende Transaktion aus und untersuchen Sie die erste fehlschlagende Anfrage. Verwenden Sie den Leitfaden für benutzerdefinierte Domains, wenn DNS oder TLS fehlerhaft ist. Behandeln Sie „ROOT_URL erzeugt localhost-Clone-Links oder der SSH-Port wird nicht weitergeleitet“ als separate Diagnose auf Anwendungsebene, sobald die Route nachgewiesen ist.

Die Gitea-Bereitstellung vollständig überprüfen

Machen Sie den Datenverkehr des ersten Benutzers nicht zum Abnahmetest für Gitea. Bereiten Sie harmlose Beispieldaten vor und führen Sie die vollständige Aktion „per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen“ aus. Notieren Sie die genaue öffentliche URL, das Ergebnis, die Image-Referenz und das mit dem Lauf verknüpfte Log-Intervall.

Ersetzen Sie den Container und wiederholen Sie den Test, ohne die Daten neu aufzubauen. Stellen Sie die Daten anschließend auf einem leeren Host wieder her. Die Wiederherstellungsbedingung lautet, dass die Repositories fsck bestehen, LFS-Objekte heruntergeladen werden können und Issues, Releases sowie Benutzerberechtigungen dem Zustand vor dem Backup entsprechen. Beobachten Sie bei jedem Durchlauf Repository-Anzahl, Git-Object-Packing, LFS-Speicher, Datenbanklatenz und Runner-Auslastung statt gewöhnlicher Seitenaufrufe und definieren Sie einen Alert für eine Verschlechterung der Transaktion statt für inaktive Container-Metriken.

Eine letzte Prüfung sollte absichtlich fehlschlagen: Verweigern Sie der Testidentität vorübergehend den Zugriff auf Postgres oder MySQL für eine stärker ausgelastete Installation sowie bei Bedarf auf eine SSH-Route. Überprüfen Sie, dass die resultierende Gitea-Meldung die relevante Grenze identifiziert, anstatt eine Datenlöschung oder einen endlosen Neustart auszulösen. Stellen Sie den gültigen Zustand wieder her und bestätigen Sie, dass dieselbe Beispieltransaktion erfolgreich ist. Nehmen Sie diese kurze Übung in die Release-Checkliste auf.

Die riskante Gitea-Änderung proben

Überwachen Sie bei Gitea eine Transaktion statt eines Prozesses: per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen. Kombinieren Sie Latenz und Fehlerrate dieser Transaktion mit Repository-Anzahl, Git-Object-Packing, LFS-Speicher, Datenbanklatenz und Runner-Auslastung statt mit gewöhnlichen Seitenaufrufen, damit ein Alert die begrenzte Komponente identifiziert.

Die Upgrade-Probe muss berücksichtigen, dass Schema-Migrationen, Repository-Hooks, Packages und Third-Party-Runner ein schrittweise durchgeführtes Gitea-Upgrade erfordern. Stellen Sie die Daten wieder her, migrieren Sie sie und führen Sie die Transaktion vor dem Austausch in der Produktion aus. Wenn ROOT_URL localhost-Clone-Links erzeugt oder der SSH-Port nicht weitergeleitet wird, löschen Sie keine Daten, nur damit der Start grün erscheint. Vergleichen Sie stattdessen in dieser Reihenfolge Version, Variablen, Mounts und die Erreichbarkeit der Abhängigkeiten.

Den wertvollen Teil von Gitea schützen

Überprüfen Sie nach dem ersten Login, welche Aktionen ein anonymer Besucher, ein gewöhnlicher Benutzer und ein Administrator jeweils ausführen können. Der zu vermeidende Gitea-Fehler besteht darin, das Installationsprogramm oder das erste Administratorkonto länger als nötig erreichbar zu lassen. Die gewünschte Richtlinie ist, das Installationsprogramm nach dem Bootstrap zu schließen, die Site-Administration einzuschränken und Runner-Registrierungstokens kurzlebig zu halten.

Behandeln Sie GITEA__security__SECRET_KEY entsprechend seiner Rolle in Gitea: Halten Sie vertrauliche Werte aus Git heraus, dokumentieren Sie die Auswirkungen einer Rotation und verwenden Sie in der Produktion niemals ein öffentliches Beispiel. Halten Sie Konten für Abhängigkeiten von menschlichen Konten getrennt, verweigern Sie ungenutzten ausgehenden Datenverkehr, soweit dies praktikabel ist, und begrenzen Sie die Arbeit, die durch Repository-Anzahl, Git-Object-Packing, LFS-Speicher, Datenbanklatenz und Runner-Auslastung beeinflusst wird, statt durch gewöhnliche Seitenaufrufe.

Was Dockup für Gitea automatisieren sollte

Für Gitea kann Dockup die Route und das TLS-Zertifikat erstellen, Mounts erhalten, Secrets bereitstellen und Postgres oder MySQL für eine stärker ausgelastete Installation sowie bei Bedarf eine SSH-Route in einem privaten Netzwerk einrichten – bei der Bereitstellung auf Dockup oder auf angebundenen Servern.

Das Release-Gate bleibt die konkrete Gitea-Transaktion: per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen. Überprüfen Sie außerdem die Wiederherstellungsbedingung: Die Repositories bestehen fsck, LFS-Objekte werden heruntergeladen und Issues, Releases sowie Benutzerberechtigungen entsprechen dem Zustand vor dem Backup. Diese beiden Prüfungen zeigen, ob die Bereitstellung funktioniert und ob sie wiederhergestellt werden kann.

Häufig gestellte Fragen

Was benötigt Gitea für eine Bereitstellung in der Produktion?

Routen Sie den Gitea-Container auf Port 3000 über einen einzigen HTTPS-Origin. Die unterstützende Netzwerkanforderung umfasst Postgres oder MySQL für eine stärker ausgelastete Installation sowie bei Bedarf eine SSH-Route. Erklären Sie Gitea erst dann für bereit, wenn Sie per HTTPS und SSH klonen, einen Commit und ein LFS-Objekt pushen, einen Issue öffnen und einen Job auf einem separat registrierten Actions runner ausführen können.

Welche Gitea-Daten gehören in ein Backup?

Machen Sie /data persistent und nehmen Sie Repositories, LFS-Objekte, Anhänge, Konfiguration und Datenbank in dasselbe Wiederherstellungsmanifest auf. Eine saubere Gitea-Wiederherstellung ist erst dann erfolgreich, wenn die Repositories fsck bestehen, LFS-Objekte heruntergeladen werden können und Issues, Releases sowie Benutzerberechtigungen dem Zustand vor dem Backup entsprechen.

Benötigt Gitea hinter einem Reverse Proxy HTTPS?

Verwenden Sie HTTPS für den öffentlichen Gitea-Origin und halten Sie Port 3000 auf der internen Route. Wenden Sie die Gitea-Einstellung korrekt an: Setzen Sie ROOT_URL und SSH_DOMAIN auf die Adressen, unter denen Benutzer tatsächlich klonen. Bei Gitea schützt HTTPS Credentials oder Benutzerinhalte während der Übertragung und sorgt für ein konsistentes, vom Origin abhängiges Verhalten der Clients.

Wie sollte ein Gitea-Upgrade getestet werden?

Stellen Sie den aktuellen Gitea-Zustand in einer isolierten Bereitstellung wieder her, wenden Sie die Zielversion an und wiederholen Sie die Abnahmetransaktion. Achten Sie besonders darauf, dass Schema-Migrationen, Repository-Hooks, Packages und Third-Party-Runner ein schrittweise durchgeführtes Gitea-Upgrade erfordern. Behalten Sie das bisherige Gitea-Image, bis die Grenzen für Datenmigration und Rollback geklärt sind.