Von Gitea zu Forgejo migrieren

Diese Seite behandelt die betriebliche Seite des Wechsels. Wenn du noch entscheidest, ob du ihn überhaupt machst, findest du den Vergleich zu Governance, Lizenz und Funktionsumfang auf Forgejo vs. Gitea.

Kurzfassung: der Wechsel von Gitea zu Forgejo ist ein Upgrade an Ort und Stelle, kein Export mit anschliessendem Import. Forgejo übernimmt die bestehende Datenbank und das Datenverzeichnis. Kein erneuter Import der Repositories, kein neues Klonen durch die Entwicklungsteams, keine Änderung an den Remote-URLs.

Das macht es zu deutlich weniger Arbeit als die meisten Plattformmigrationen. Es heisst aber auch, dass die übliche Upgrade-Disziplin gilt, denn du lässt Schema-Migrationen gegen deine Produktionsdatenbank laufen.

Vor dem Start

Mach ein Backup und stelle es einmal testweise wieder her. Das ist der Schritt, den man überspringt und dann bereut. Die Migration ändert das Datenbankschema, und der Rückweg ist eine Wiederherstellung und kein Downgrade (siehe die Warnung weiter unten). Ein Backup, das du noch nie zurückgespielt hast, ist eine Vermutung.

Prüfe deinen Versionspfad. Die Kompatibilität ist nicht beliebig:

Es sind also zwei Schritte und nicht einer. Lande zuerst auf Forgejo v10.0.x, überzeug dich, dass die Instanz gesund ist, und geh dann die Forgejo-Releases weiter hoch. Gitea-Versionen neuer als v1.22.x liegen jenseits des Punktes, an dem die beiden Codebasen noch zusammenpassen: Forgejo wurde Anfang 2024 zum harten Fork und hat sich seither auseinanderentwickelt.

Sieh deine Anpassungen durch. Wenn du Templates gepatcht oder eigenes CSS ergänzt hast, vergleich dein Template-Verzeichnis mit dem Original und notier, was du geändert hast. Anpassungen sind die häufigste Ursache für eine Migration, die technisch gelingt und sichtbar kaputt ist.

Prüf deine Docker-Version, falls du in Containern läufst. Docker 20.10.6 oder neuer vermeidet eine Klasse von Problemen, die sich anhand der Symptome schlecht eingrenzen lässt.

Beratung anfragen

Die Migration

1. Queues leeren.

forgejo manager flush-queues

Queues halten serialisierte Daten in einem versionsabhängigen Format. Was beim Versionswechsel noch aussteht, ist danach womöglich nicht mehr lesbar. Läuft der Befehl in einen Timeout, erhöh --timeout und lass ihn nochmals laufen, statt weiterzugehen.

2. Binary oder Container-Image austauschen.

Ersetze das Gitea-Binary oder -Image durch Forgejo v10.0.x. Die Datenbankmigrationen laufen beim ersten Start automatisch.

Forgejo behält den Binary-Namen gitea samt symbolischen Links, und zwar genau dafür, dass bestehende systemd-Units, Skripte und Cronjobs weiterlaufen. Du musst deine Service-Dateien in diesem Schritt nicht umschreiben.

3. Prüfen.

forgejo doctor check --all --log-file /tmp/doctor.log

Öffne danach die Weboberfläche und sieh dir an, was kein Skript prüfen kann: ein Repository, das dir wichtig ist, einen Pull Request, einen CI-Lauf, einen Klon über SSH und die Anmeldung über die Authentifizierungsquelle, die du nutzt.

4. Die Releases weiter hochgehen.

Sobald v10.0.x gesund läuft, aktualisier auf ein aktuelles Forgejo-Release. Scheitert ein Upgrade über mehrere Versionen hinweg, wiederhol es Release-Serie für Release-Serie, um die unglückliche zu finden.

Die Einbahnstrasse

Ein Downgrade wird nicht unterstützt und aktiv verhindert. Sobald Forgejo die Datenbank migriert hat, hindern Versionsprüfungen ein älteres Binary am Start dagegen. Zurück geht es nur über die Wiederherstellung des Backups, und alles, was seither geschrieben wurde, ist verloren.

Plan das Wartungsfenster entsprechend: der Entscheidungspunkt liegt vor dem ersten Start von Forgejo, nicht danach.

Was üblicherweise schiefgeht

• Übersprungene oder ungetestete Backups. Der Schaden ist nicht "die Migration ging schief", sondern "die Migration ging schief und wir kamen nicht zurück".
• Eigene Templates. Diese überleben das Upgrade und rendern dann gegen geändertes Markup. Vorher vergleichen.
• Versionssprünge. Der Versuch, direkt von einem alten Gitea auf ein aktuelles Forgejo zu gehen, statt zuerst auf v10.0.x zu landen.
• Ausstehende Queue-Einträge. Das Leeren überspringen und es später merken.
• Authentifizierung. LDAP, OAuth und SSO gehören nach dem Wechsel ausdrücklich getestet und nicht angenommen.

Wo VSHN ins Bild kommt

Wir betreiben Forgejo produktiv und sind diesen Weg gegangen. Drei Arten der Zusammenarbeit, je nachdem, wie viel du behalten willst:

Selbst weiterbetreiben, mit Hilfe für den Wechsel. Wir planen den Versionspfad, sehen deine Anpassungen durch, machen einen Probelauf gegen eine wiederhergestellte Kopie deiner Daten und bleiben während des Wartungsfensters erreichbar.

Betrieb abgeben, Infrastruktur behalten. Wir betreiben die Instanz auf deiner Cloud oder deiner Plattform vor Ort: Upgrades, Backups, Monitoring und Incident Response, wobei die Daten bleiben, wo sie sind.

Auf eine verwaltete Instanz wechseln. Codey ist eine dedizierte Forgejo-Instanz, betrieben von VSHN in der Schweiz, ab CHF 39 pro Monat, mit CI/CD über Forgejo Actions, Package-Hosting und Backups. Wenn du ohnehin ein Wartungsfenster planst, um von Gitea wegzukommen, kostet der Wechsel auf eine verwaltete Instanz etwa gleich viel Aufwand wie der auf eine selbst betriebene.

Unsicher, was passt? Buch eine kostenlose Migrationsanalyse, und wir bilden dein aktuelles Setup auf einen Versionspfad und ein Fenster ab.