So migrieren Sie von Gitea zu Forgejo, ohne Ihre Repositories zu beschädigen

Sie stoppen Gitea, installieren Forgejo, kopieren app.ini und Ihr Datenverzeichnis und starten den Dienst so, wie es jeder Migrationsleitfaden beschreibt. Die Web-UI kommt hoch. Dann schlägt die Datenbankmigration fehl, oder schlimmer, Forgejo weigert sich zu starten, weil Ihre Schema-Version zu neu ist, um sie zu verstehen. Sie sind auf Gitea 1.23 oder neuer, und das einfache In-Place-Upgrade, das überall dokumentiert wird, gilt für Sie nicht mehr.

Forgejo wurde Anfang 2024 zu einem Hard Fork von Gitea, und die beiden Projekte haben sich seither auf Ebene des Datenbankschemas auseinanderentwickelt. Wie Sie Gitea zu Forgejo migrieren, hängt jetzt vollständig von Ihrer Gitea-Version ab. Dieser Leitfaden gibt Ihnen den genauen Pfad für Ihre Version, die vollständigen Befehle für native und Docker-Installationen, die Workarounds für Gitea 1.23+ und eine Prüfliste, damit Sie migrieren, ohne Repositories, Issues oder Benutzer zu verlieren.

Kurzfassung

• Die Versionsklippe ist real. Forgejo v10.0 war das letzte Release, das ein transparentes direktes Upgrade von Gitea unterstützte. Gitea v1.22 ist die höchste Version, die den unterstützten direkten Pfad nutzen kann.
• Bei Gitea v1.22 oder früher: migrieren Sie zuerst zu Forgejo v10.0.x, aktualisieren Sie dann Forgejo v10 auf die aktuelle Version (v15). Zwei Schritte, beide unterstützt.
• Bei Gitea v1.23 oder neuer: gibt es keinen offiziell unterstützten direkten Pfad. Sie wählen zwischen einem SQL-/Schema-Downgrade, Community-Migrationsskripten, einer Repo-/API-Migration oder einer Staging-Migration auf einem frischen Server mit einer dieser Methoden. Jede bringt einen anderen Datenverlust-Kompromiss mit sich.
• Sichern Sie Ihr Datenverzeichnis und Ihre Datenbank, bevor Sie irgendetwas anfassen. Jeder Pfad unten setzt voraus, dass Sie ein wiederherstellbares Backup haben. Bei den nicht unterstützten Pfaden gilt das doppelt.
• Manche Dinge brauchen nach der Migration immer Aufmerksamkeit: planen Sie, Personal Access Tokens neu zu erstellen oder zu prüfen, Actions-Runner neu zu registrieren sowie den Bleve-Suchindex zu löschen und neu aufzubauen. Planen Sie dies unabhängig vom gewählten Pfad ein.
• Migrieren ist nicht verpflichtend. Gitea wird aktiv weiterentwickelt. Die Entscheidung "bei Gitea bleiben" ist gerechtfertigt, wenn das Migrationsrisiko den Nutzen für Ihre Situation übersteigt.

Nicht Teil dieses Leitfadens: die Migration von Gogs, GitHub oder GitLab zu Forgejo sowie das Einrichten von Forgejo Actions von Grund auf.

Voraussetzungen / Was Sie benötigen

Bevor Sie auch nur einen Befehl ausführen, stellen Sie sicher, dass Sie ein vollständiges, wiederherstellbares Backup von zwei Dingen haben: Ihrem Gitea-Datenverzeichnis (/var/lib/gitea bei einer nativen Standardinstallation) und Ihrer Datenbank. Bei SQLite liegt diese Datei innerhalb des Datenverzeichnisses; bei PostgreSQL oder MySQL sichern Sie sie separat mit pg_dump oder mysqldump. Eine Migration ohne geprüftes Backup ist keine Migration, sondern ein Glücksspiel.

Sie benötigen außerdem:

• Ihre aktuelle Gitea-Version. Führen Sie aus gitea --version (oder docker exec <container> gitea --version). Diese Zahl entscheidet über Ihren gesamten Weg.
• Ihr Datenbanktyp: SQLite, PostgreSQL oder MySQL. Manche Workarounds sind datenbankspezifisch.
• Root- oder Sudo-Zugriff auf den Server.
• Ein Bewusstsein dafür, dass der unterstützte Pfad Forgejo v10.0 als Zwischenschritt installiert. Forgejo v10.0 ist seit dem 16. April 2025 EOL. Sie installieren es nur für die Dauer der Migration und aktualisieren sofort davon weg.

Warum der direkte Upgrade-Pfad wegfiel

Im Dezember 2024 veröffentlichte das Forgejo-Projekt eine Kompatibilitätserklärung das eine klare Grenze zog: "Zukünftige Forgejo-Versionen unterstützen keine Upgrades von Gitea-Instanzen mit Version v1.23 oder höher." Dieser Satz ist das ganze Problem in einer Zeile.

Als Forgejo Anfang 2024 von Gitea abgespalten wurde, entwickelten sich die beiden Codebasen weiter auseinander, und die Datenbankschemata drifteten auseinander. Forgejo hielt ein Kompatibilitätsfenster offen, damit bestehende Gitea-Betreiber wechseln konnten, aber dieses Fenster hatte ein Ende. Forgejo v10.0, veröffentlicht am 16. Januar 2025, war "the last version to allow a transparent upgrade from Gitea v1.22 or lower." Alles, was neuer als v10.0 ist, liest keine Gitea-Datenbank mehr direkt ein.

Das Timing ist es, worüber Leute stolpern. Gitea v1.23 erschien Ende 2024, und die das aktuelle Gitea-Release ist Stand Juni 2026 v1.26.4. Wenn Sie Ihre Gitea-Instanz einigermaßen aktuell gehalten haben, sind Sie bereits über die Klippe hinaus, und die Standard-Tutorials beschreiben Ihre Situation nicht mehr.

Kernaussage: Der unterstützte direkte Pfad endet bei Gitea v1.22. Alles Neuere braucht einen zusätzlichen Schritt.

Finden Sie Ihren Migrationspfad anhand der Gitea-Version

Führen Sie aus gitea --version, suchen Sie Ihre Zeile und folgen Sie dem Pfad in der dritten Spalte. Alles andere in diesem Leitfaden sind die Details hinter diesen Zeilen.

Die Aussagen zur Versionskompatibilität stammen direkt aus der offizielle Forgejo-Kompatibilitätsankündigung: Gitea bis v1.21 kann zu Forgejo v7.0 bis v10.0 wechseln, und Gitea v1.22 kann zu Forgejo v8.0 bis v10.0 wechseln. Beide enden bei v10.0 als letztem unterstützten direkten Zielwert.

Unter der Versionsfrage liegen drei Migrationsstrategien, und es hilft, sie vor den Schritt-für-Schritt-Anleitungen zu betrachten:

• Vor Ort, auf demselben Server. Tauschen Sie das Binary oder Container-Image auf der bestehenden Box aus. Geringster Aufwand, wenn Ihre Version das unterstützt; erfordert den Zwischenschritt v10.0.
• Staging auf einem frischen Server. Stellen Sie einen neuen Server bereit und nutzen Sie ihn als sicheres Ziel für die Migrationsmethode, die zu Ihrer Gitea-Version passt. Das schützt die ursprüngliche Gitea-Box und erleichtert das Rollback, umgeht aber nicht das Datenbankschema-Problem bei Gitea 1.23+.
• Repo-/API-Migration. Verwenden Sie die Migrationstools von Forgejo, um Repositories von der alten Gitea-Instanz zu holen. Die Git-Historie ist der zuverlässige Teil; Metadaten wie Issues, PRs, Labels, Releases, Wiki-Daten und Kommentare sollten als Best-Effort behandelt und Repo für Repo geprüft werden.

Der unterstützte Pfad: Gitea v1.22 oder früher

Wenn Sie Gitea v1.22 oder früher verwenden, gilt der offizielle Migrationsdokumentation beschreiben einen zweistufigen Pfad: zuerst zu Forgejo v10.0.x migrieren, dann Forgejo v10 auf die aktuelle Version aktualisieren. Der erste Schritt ist ein direkter Austausch, da Forgejo v10.x eine Gitea-v1.22-Datenbank einliest; der zweite Schritt ist ein normales Forgejo-Upgrade.

Es gibt zwei Möglichkeiten, dies zu tun, je nachdem, wie Gitea auf Ihrem Server läuft. Wählen Sie die, die zu Ihrem bestehenden Setup passt. Wenn Gitea als Systemdienst läuft, nutzen Sie den nativen Pfad. Wenn Gitea in einem Container läuft, nutzen Sie den Docker-Pfad. Forgejo v10.x fungiert als direkter Ersatz für Gitea v1.22.x.

Nativer (systemd-)Pfad

Sichern Sie zuerst. Installieren Sie dann Forgejo v10.0.x über das Paket Ihrer Distribution oder das auf v10.0 festgelegte Release-Binary. Stoppen Sie Gitea, bevor Sie irgendetwas kopieren. Ein laufender Dienst, der während des Kopiervorgangs in sein Datenverzeichnis schreibt, beschädigt die Kopie.

# Stop the running Gitea service before touching its data
systemctl stop gitea

Kopieren Sie die Konfiguration und das Datenverzeichnis an die Speicherorte von Forgejo und korrigieren Sie anschließend die Besitzrechte. Die Konfigurationsdatei muss für die Gruppe forgejo lesbar sein; die Daten müssen dem Benutzer forgejo gehören.

# Copy the existing Gitea config to Forgejo's config path
cp /etc/gitea/app.ini /etc/forgejo/app.ini

# Back up the copied config before rewriting paths
cp /etc/forgejo/app.ini /etc/forgejo/app.ini.bak

# Update old Gitea data paths to Forgejo data paths
sed -i 's#/var/lib/gitea#/var/lib/forgejo#g' /etc/forgejo/app.ini

# Forgejo reads its config as the forgejo group; grant group write
chown root:forgejo /etc/forgejo/app.ini && chmod g+w /etc/forgejo/app.ini

# Copy the data directory and hand ownership to the forgejo user
rsync -aHAX --numeric-ids /var/lib/gitea/ /var/lib/forgejo/
chown -R forgejo:forgejo /var/lib/forgejo

Starten Sie Forgejo und aktivieren Sie es beim Booten.

# Start Forgejo and enable it at boot
systemctl start forgejo && systemctl enable forgejo

Bevor Sie von v10.0 aktualisieren, leeren Sie die Warteschlangen, damit beim Versionssprung keine laufenden Aufgaben verloren gehen.

# Flush pending queue items before the version upgrade
forgejo manager flush-queues

Aktualisieren Sie nun Forgejo v10.0.x auf das aktuelle Release, indem Sie das Binary durch v15 ersetzen und den Dienst neu starten, gemäß dem Standard Forgejo-Upgrade-Leitfaden. Führen Sie nach beiden Schritten den Doctor aus, um die Datenbank zu prüfen und zu reparieren, was möglich ist.

# Check everything; write a log you can read if something is wrong
forgejo doctor check --all --log-file /tmp/doctor.log

Lesen Sie /tmp/doctor.log bevor Sie eine automatische Korrektur anwenden. Verwenden Sie --fix nur dann, wenn die Doctor-Ausgabe eine bestimmte Reparatur benennt, die Sie verstehen, oder wenn Sie einem offiziellen Fehlerbehebungspfad folgen.

Wenn der Doctor keine kritischen Fehler meldet und die Web-UI Ihre Repositories anzeigt, ist die erste Migration abgeschlossen.

Docker-/Container-Pfad

Wenn Gitea als Container lief, betreiben Sie Forgejo auf dieselbe Weise. Verwenden Sie das Forgejo-v10.x-Image als direkten Ersatz für Ihr Gitea-v1.22.x-Image und verweisen Sie es auf dasselbe Datenvolume und dieselbe Datenbank. Stellen Sie zuerst sicher, dass Ihre Docker-Version mindestens 20.10.6 ist. Ältere Versionen führen bei Forgejo-Containern zu undefiniertem Verhalten.

Das eine container-spezifische Detail, über das Leute stolpern: Umgebungsvariablen. Forgejo behält das Präfix GITEA_ aus Kompatibilitätsgründen bei, aber die Dokumentation empfiehlt, beide Präfixe zu übergeben, damit Ihre Konfiguration eine künftige Forgejo-Version übersteht, die die alten Namen fallen lässt.

# docker-compose.yml (excerpt): pass both prefixes for forward compatibility
environment:
  - GITEA__database__DB_TYPE=postgres
  - FORGEJO__database__DB_TYPE=postgres
  # ...repeat the dual-prefix pattern for every config override you pass

Bei rootless Containern müssen die Daten dem Benutzer 1000 und der Gruppe 1000 gehören, passend zum Laufzeitbenutzer des rootless-Images. Nachdem der Container unter v10.x gestartet ist, führen Sie dasselbe aus forgejo doctor check --all innerhalb des Containers, aktualisieren Sie dann den Image-Tag auf das aktuelle v15-Release und starten Sie neu.

Wenn Sie Gitea v1.23 oder neuer verwenden

Hier hören die Standardleitfäden auf, und genau hier stehen die meisten aktuellen Installationen tatsächlich. Es gibt keinen offiziell unterstützten direkten Pfad ab Gitea v1.23+, sodass jede Option unten entweder aus der Community stammt oder verlustbehaftet ist. Bevor Sie eine davon ausführen, erstellen Sie ein vollständiges Backup Ihres Datenverzeichnisses und Ihrer Datenbank und stellen Sie sicher, dass Sie es wiederherstellen können. Diese Vorgehensweisen verändern Produktionsdaten; das Backup ist Ihr einziges Rückgängig.

Die drei Optionen unterscheiden sich im Risiko und darin, wie viel sie erhalten. Wählen Sie die, deren Kompromiss Sie akzeptieren können.

Option A: SQL-Schema-Downgrade / Versionspatch

Der schmalste Workaround setzt die Datenbankschema-Version herab, sodass Forgejo v10 sie als v1.22-Datenbank behandelt.

Hinweis: Betrachten Sie die Versionsaktualisierung nicht für sich allein als vollständiges Downgrade. Die erfasste Migrationsversion und das tatsächliche Schema müssen übereinstimmen. Testen Sie bei Gitea 1.23.x das vollständige Downgrade zuerst an einer Kopie und vergleichen Sie das Schema, bevor Sie Forgejo darauf ansetzen.

Ein Forgejo-Maintainer beschrieb das SQL in Codeberg-Issue #7638:

-- Downgrade the recorded schema version to the v1.22 baseline (PostgreSQL/MySQL)
UPDATE version SET version=305 WHERE id=1;

Danach folgen Sie dem unterstützten Pfad, als wären Sie auf v1.22. Der entscheidende Vorbehalt: Der Maintainer bestätigte dies nur speziell für Gitea v1.23.1, nicht für die gesamte v1.23.x-Reihe. Die Schema-Versionsnummer ist exakt; wird der falsche Zielwert auf die falsche Gitea-Version angewendet, kann die Datenbank in einem Zustand landen, aus dem keine Migration mehr herausführt. Dies gilt für PostgreSQL/MySQL, ist nicht offiziell unterstützt und nicht als allgemeines Verfahren getestet.

Profi-Tipp: Das direkte Setzen von version=305 überspringt die Migration von 304 auf 305, die die Kodierung der TOTP-Secrets geändert hat. Codeberg-Issue #8210 dokumentiert, dass dies die Zwei-Faktor-Authentifizierung für betroffene Benutzer beschädigt. Die Lösung besteht darin, die Version auf 304 zu setzen und die Migration laufen zu lassen, oder die Zeilen der Tabelle two_factor zu leeren, damit sich Benutzer neu registrieren. Überspringen Sie dies nicht, wenn ein Konto TOTP verwendet.

Option B: Sequentielle SQL-Downgrade-Skripte (Gitea 1.24–1.25.2)

Für Versionen zwischen 1.24 und 1.25.2 reicht ein einzelner Versionspatch nicht aus: Das Schema durchlief mehrere Zwischenzustände. Die Community-Skripte unter xlrl/prepare-gitea-migration-to-forgejo führen das Schema durch die Zwischenversionen zurück zu v1.22, wonach Sie den unterstützten Pfad nehmen. Diese Skripte sind Community-Arbeit, kein autoritatives Verfahren, und zielen primär auf SQLite ab. Führen Sie sie nur gegen eine Datenbank aus, die Sie bereits gesichert haben.

Option C: API-Migration Repo für Repo (Gitea 1.26+ oder jede Version)

Der Repo-/API-Pfad erhält Git-Daten am zuverlässigsten. Je nach Quelle, Berechtigungen und Migrationsmethode können auch optionale Metadaten wie Issues, Pull Requests, Labels, Meilensteine, Releases, Wiki-Daten und Kommentare verfügbar sein, behandeln Sie diese aber als Best-Effort und prüfen Sie sie Repo für Repo. Für ein reines Code-Archiv ist das meist unproblematisch; bei einem Server, bei dem der Issue-Tracker das Gedächtnis des Teams ist, testen Sie die Metadatenübertragung, bevor Sie sich für diesen Pfad entscheiden.

Zwei experimentelle Tools versuchen umfassendere Migrationen für 1.23+, haben aber ihre eigenen Lücken. pacnpal/gitea2forgejo (GitHub) erstellt einen vollständigen Dump plus API-Sync und benötigt einen passenden SECRET_KEY, damit verschlüsselte Felder übertragen werden, verschiebt aber keine Personal Access Tokens, Actions-Runner, Webhook-Callback-URLs oder 2FA. nicoverbruggen/gitea-to-forgejo (GitHub) ist ein Podman-basiertes experimentelles Tool, das Benutzer, Keys, Organisationen, Repos, Issues, PRs, Releases und Mirrors überträgt, jedoch keine 2FA-Tokens, Actions-Laufzeitdaten oder verwaiste OCI-Paketmanifeste. Behandeln Sie beide als experimentell und prüfen Sie das Ergebnis anhand der Transfermatrix unten.

Kernaussage: Es gibt keinen offiziell unterstützten direkten Pfad ab Gitea 1.23+. Wählen Sie die Option, deren Datenverlust-Kompromiss Sie akzeptieren können, und sichern Sie, bevor Sie beginnen.

Migration auf einem frischen Server ist sicherer, umgeht aber nicht die Versionsklippe

Ein frischer Server ist der sicherste Ort, um die Migration vorzubereiten und zu prüfen, aber er ist kein eigenständiger Schema-Kompatibilitätspfad. Wenn Ihre Quelle Gitea v1.22 oder älter ist, installieren Sie zuerst Forgejo v10.0.x auf dem Ziel, stellen Sie die Gitea-Daten dort wieder her oder kopieren Sie sie, lassen Sie Forgejo die unterstützten Datenbankmigrationen durchführen und aktualisieren Sie diese Forgejo-v10-Instanz anschließend auf die aktuelle Forgejo-Version.

Wenn Ihre Quelle Gitea v1.23 oder neuer ist, stellen Sie die Gitea-Datenbank nicht einfach direkt im aktuellen Forgejo wieder her und erwarten, dass es startet. Sie brauchen weiterhin einen der oben genannten nicht unterstützten 1.23+-Ansätze: ein gestuftes SQL-Downgrade oder Revert, ein Community-Migrationstool oder eine Repo-/API-Migration. Der frische Server verringert das Rollback-Risiko, da die ursprüngliche Gitea-Box unangetastet bleibt; er beseitigt jedoch nicht die Notwendigkeit, die nicht übereinstimmende Datenbankversion zu behandeln.

Hier ist Cloudzys Ein-Klick-Forgejo App kann helfen: Nutzen Sie sie als saubere Zielinstanz und führen Sie dann die Migrationsmethode aus, die zu Ihrer Gitea-Version passt. Cloudzys Marketplace-Image liefert Ihnen ein einsatzbereites Forgejo-Ziel auf unserem leistungsstarken VPS, sodass Sie sich auf die Wiederherstellung, Verifizierung und Umstellung konzentrieren können statt auf die Erstinstallation. Der Migrationsplan hängt weiterhin davon ab, ob Sie vor oder nach der Gitea-1.22-Klippe stehen.

Was übertragen wird und was Sie neu erledigen müssen

Ein Teil Ihrer Daten wird automatisch übertragen, ein Teil nur, wenn eine Bedingung erfüllt ist, und ein Teil wird nie übertragen und muss von Hand neu erstellt werden. Zu wissen, was wohin gehört, bevor Sie beginnen, macht den Unterschied zwischen einer sauberen Umstellung und einer Woche verwirrter Benutzer aus.

Vier Punkte treffen am härtesten, weil sie stillschweigend brechen oder jeden Benutzer betreffen. Behandeln Sie sie deshalb bewusst: Benutzer sollten ihre Personal Access Tokens neu erstellen oder überprüfen, Sie müssen Ihre Actions-Runner gegen den neuen Hostnamen neu registrieren, Sie müssen den Bleve-Suchindex löschen, damit Forgejo ihn sauber neu aufbaut, und Sie müssen jegliche uses: kurze Referenzen in Ihren Actions-Workflows zu vollständigen GitHub-URLs, da Forgejo und Gitea Actions aus separaten Mirrors beziehen und eine relative Referenz an die falsche Stelle auflöst.

Profi-Tipp: Wenn Sie Gitea und Forgejo während der Migration parallel betreiben und beide auf dieselbe Redis-Instanz zeigen, stellen Sie Forgejo vor dem Start auf Redis db=1 um. Beide verwenden standardmäßig db=0, und wenn sie sich diese teilen, verbraucht Gitea die Migrationsereignisse von Forgejo und zerstört die Migrationswarteschlange. (blog.mei-home.net documents this exact failure.)

Kernaussage: Personal Access Tokens, Actions-Runner, Deploy Keys pro Repo und der Bleve-Suchindex sind immer manuell. Planen Sie sie als Migrationsaufgaben ein, nicht als Nachgedanken.

Prüfen, ob die Migration erfolgreich war

Beginnen Sie mit dem Doctor, prüfen Sie dann die Zahlen und testen Sie anschließend die Dinge, die Benutzer tatsächlich tun. Der Doctor erkennt Probleme auf Datenbankebene; die manuellen Prüfungen erkennen Datenverlust- und Zugriffsprobleme, die der Doctor nicht sehen kann.

1. Führen Sie aus forgejo doctor check --all --log-file /tmp/doctor.log, lesen Sie dann das Log, bevor Sie Änderungen vornehmen. Verwenden Sie --fix nur für eine bestimmte Reparatur, die Sie verstehen.
2. Bestätigen Sie, dass die Anzahl der Repositories, die Anzahl der Issues und PRs sowie die Anzahl der LFS-Objekte und die Gesamtgröße mit Ihren Zahlen vor der Migration übereinstimmen. Eine Abweichung bedeutet, dass etwas nicht übertragen wurde.
3. Testen Sie einen SSH-Push und -Pull. Wenn Clients eine Host-Key-Fehlermeldung erhalten, haben Sie /etc/ssh/ssh_host_* nicht auf den neuen Server kopiert.
4. Melden Sie sich an und bestätigen Sie, dass 2FA für ein Konto funktioniert, das es nutzt. Wenn TOTP nicht funktioniert, siehe den Vorbehalt zu Option A oben.
5. Erstellen Sie Personal Access Tokens neu, registrieren Sie Actions-Runner neu und führen Sie einen Test-Workflow aus.

Einige Symptome nach der Migration haben bekannte Ursachen. Ein fehlendes Favicon oder Logo bedeutet, dass Ihre Branding-Assets noch in public/assets/img/ statt in custom/ liegen, wo Forgejo sie jetzt erwartet. 404-Fehler bei Paketrouten deuten auf falsch konfigurierte Speicherpfade hin. Actions, die mit "repository not found" fehlschlagen, sind das uses: Mirror-Problem. Wechseln Sie zu vollständigen URLs. Eine leere Seite oder ein 500-Fehler nach dem Login bei einer SQLite-Datenbank bedeutet, dass Sie unter dem Minimum liegen, das die Upgrade-Dokumentation setzte bei Forgejo v1.19.3-0 an.

Wann es sinnvoll ist, bei Gitea zu bleiben

Migrieren ist eine Wahl, keine Pflicht. Wenn Sie bereits über die Klippe hinaus sind und die Migrationskomplexität den Nutzen bei Verwaltung oder Funktionen für Ihre Situation übersteigt, ist das Bleiben bei Gitea eine legitime Wahl. Gitea wird aktiv gepflegt (mehrere Releases pro Monat, derzeit bei v1.26.4), und CommitGo bietet kommerzielle Optionen an, darunter Gitea Enterprise, Gitea Cloud und die SOC-2-Type-2-Zertifizierung für Teams, die sie benötigen.

Es gibt auch das Bedenken hinsichtlich des EOL-Zwischenschritts, das man ehrlich abwägen sollte. Der unterstützte direkte Pfad erfordert die vorübergehende Installation von Forgejo v10.0, das seit April 2025 EOL ist. Das ist als vorübergehender Migrationsschritt akzeptabel, von dem Sie sofort wieder wegaktualisieren, aber manche Betreiber werden aus Richtliniengründen Einwände haben. Für sie kann eine Repo-/API-Migration in eine frische Forgejo-Instanz den EOL-Zwischenschritt vollständig vermeiden, während das Staging auf einem frischen Server weiterhin von der gewählten Migrationsmethode abhängt.

Wenn Ihr Grund für den Wechsel die Entwicklungsaktivität ist, stützen die Daten Forgejo als das aktivere Projekt: Eine Analyse von honeypot.net zählte 3.039 Forgejo-Commits gegenüber 1.228 Gitea-Commits im Zeitraum Juli 2024 bis Mai 2025 sowie 232 Forgejo-Mitwirkende gegenüber 153 bei Gitea im Jahr bis Mai 2025. Das ist ein Signal unter mehreren; wägen Sie es gegen Ihr Migrationsrisiko ab, statt es als ausschlaggebend zu behandeln.

Kernaussage: Migrieren ist nicht verpflichtend. Die Entscheidung ist eine Abwägung zwischen Vorlieben bei Verwaltung und Aktivität gegen das Migrationsrisiko, und beide Optionen sind vertretbar.

Wählen Sie Ihren Pfad und sichern Sie zuerst

Ihr Migrationspfad hängt von einer Zahl ab: Ihrer Gitea-Version. Bei v1.22 oder früher gehen Sie den unterstützten zweistufigen Pfad über Forgejo v10. Bei v1.23 oder neuer wählen Sie einen Workaround nach dem Datenverlust, den Sie akzeptieren können: SQL-/Schema-Downgrade, Community-Skripte, Repo-/API-Migration oder eine Staging-Migration auf einem frischen Server. Welchen Pfad Sie auch wählen, sichern Sie zuerst Ihr Datenverzeichnis und Ihre Datenbank, führen Sie aus forgejo doctor danach aus und bestätigen Sie, dass Ihre Anzahl an Repositories, Issues und LFS-Objekten mit dem übereinstimmt, womit Sie gestartet sind.

Bestimmen Sie Ihre Version, erstellen Sie das Backup und folgen Sie der passenden Zeile. Der Pfad ist aufwendiger, als die alten Tutorials versprachen, aber er ist klar definiert, sobald Sie wissen, wo Sie an der Versionsklippe stehen.

Häufig gestellte Fragen

Kann ich direkt von Gitea auf Forgejo upgraden?

Ja, wenn Sie Gitea v1.22 oder früher betreiben: direkt auf Forgejo v10.0 upgraden, dann Forgejo v10 auf die aktuelle Version aktualisieren. Nein, wenn Sie Gitea v1.23 oder neuer betreiben. Forgejo v10.0 war das letzte Release mit Unterstützung für ein transparentes direktes Upgrade, sodass neuere Gitea-Versionen stattdessen einen Workaround benötigen.

Welche Gitea-Version ist mit Forgejo kompatibel?

Gitea v1.22 und früher haben einen unterstützten direkten Upgrade-Pfad zu Forgejo (bis Forgejo v10.0, dann weiter zur aktuellen Version). Gitea v1.23 und neuer haben keinen offiziell unterstützten direkten Pfad, da Forgejo ab den Releases nach v10.0 keine transparenten Upgrades mehr von Gitea v1.23+ unterstützt.

Kann ich von Gitea 1.26 zu Forgejo migrieren?

Ja, aber nicht über ein unterstütztes direktes Upgrade. Ihre Optionen sind eine Repo-/API-Migration, bei der die Git-Historie der zuverlässige Teil ist und Metadaten Repo für Repo getestet werden müssen, ein experimentelles Migrationsskript oder eine Staging-Migration auf einem frischen Server mit einer der oben genannten nicht unterstützten 1.23+-Methoden. Es gibt keinen offiziell unterstützten In-Place-Pfad ab Gitea 1.26.

Werden meine Personal Access Tokens übertragen?

Planen Sie ein, Personal Access Tokens nach der Migration neu zu erstellen oder zu rotieren. Manche Migrationspfade erhalten sie nicht, und selbst wenn Tokens erhalten bleiben, sollten Benutzer die Scopes prüfen, bevor sie sich wieder darauf verlassen. Skripte oder Integrationen, die alte Tokens verwenden, sollten nach der Umstellung getestet und aktualisiert werden.

Funktionieren meine Gitea-Actions-Workflows in Forgejo?

Größtenteils, mit zwei erforderlichen Korrekturen. Workflow uses: kurze Referenzen brechen, weil Forgejo und Gitea Actions aus separaten Mirrors beziehen. Wechseln Sie sie zu vollständigen GitHub-URLs (zum Beispiel uses: https://github.com/sammcj/dotenv-output-action@main). Sie müssen außerdem Ihre Actions-Runner neu registrieren, da deren Registrierungstoken an den alten Hostnamen gebunden sind.

Was ist mit der Migration von Gogs zu Forgejo?

Das ist eine andere Migration mit einem anderen Pfad und liegt außerhalb des Rahmens dieses Leitfadens. Dieser Leitfaden behandelt speziell Gitea zu Forgejo; bei einer Gogs-Quelle konsultieren Sie die offizielle Migrationsdokumentation von Forgejo für das Gogs-spezifische Verfahren.