Jak migrować z Gitea do Forgejo bez psucia repozytoriów

Zatrzymujesz Gitea, instalujesz Forgejo, kopiujesz app.ini i katalog danych, a następnie uruchamiasz usługę dokładnie tak, jak opisuje każdy poradnik migracyjny. Interfejs webowy się uruchamia. A potem migracja bazy danych kończy się niepowodzeniem, albo, co gorsza, Forgejo odmawia uruchomienia, bo wersja twojego schematu jest zbyt nowa, aby ją rozpoznać. Masz Gitea 1.23 lub nowszą, a prosta aktualizacja w miejscu, którą opisuje każdy poradnik, już cię nie dotyczy.

Forgejo stało się twardym forkiem Gitea na początku 2024 roku i od tego czasu oba projekty rozeszły się na poziomie schematu bazy danych. To, jak migrujesz z Gitea do Forgejo, zależy teraz całkowicie od Twojej wersji Gitea. Ten przewodnik podaje dokładną ścieżkę dla Twojej wersji, pełne komendy zarówno dla instalacji natywnych, jak i Docker, obejścia dla Gitea 1.23+, oraz listę kontrolną weryfikacji, dzięki czemu przeprowadzisz migrację bez utraty repozytoriów, issues czy użytkowników.

TL;DR

• Ta wersyjna "przepaść" jest realna. Forgejo v10.0 było ostatnim wydaniem wspierającym bezproblemową bezpośrednią aktualizację z Gitea. Gitea v1.22 to najwyższa wersja, która może skorzystać ze wspieranej ścieżki bezpośredniej.
• Na Gitea v1.22 lub wcześniejszej: najpierw migruj do Forgejo v10.0.x, a następnie zaktualizuj Forgejo v10 do bieżącego wydania (v15). Dwa kroki, oba wspierane.
• Na Gitea v1.23 lub nowszej: nie istnieje oficjalnie wspierana bezpośrednia ścieżka. Wybierasz między obniżeniem wersji SQL/schematu, skryptami migracyjnymi społeczności, migracją repo/API lub migracją na nowym, przygotowanym serwerze przy użyciu jednej z tych metod. Każda wiąże się z innym kompromisem dotyczącym utraty danych.
• Zrób kopię zapasową katalogu danych i bazy danych, zanim czegokolwiek dotkniesz. Każda ścieżka poniżej zakłada, że masz możliwą do przywrócenia kopię zapasową. Ścieżki niewspierane zakładają to podwójnie.
• Niektóre rzeczy zawsze wymagają uwagi po migracji: zaplanuj odtworzenie lub audyt Personal Access Tokens, ponowną rejestrację runnerów Actions oraz usunięcie i odbudowanie indeksu wyszukiwania Bleve. Zaplanuj to bez względu na wybraną ścieżkę.
• Migracja nie jest obowiązkowa. Gitea jest aktywnie rozwijana. Decyzja "pozostań przy Gitea" ma sens, jeśli ryzyko migracji przewyższa korzyści w Twojej sytuacji.

Poza zakresem tego tekstu: migracja z Gogs, GitHub lub GitLab do Forgejo oraz konfiguracja Forgejo Actions od zera.

Wymagania wstępne / czego będziesz potrzebować

Zanim uruchomisz choć jedną komendę, upewnij się, że masz pełną, możliwą do przywrócenia kopię zapasową dwóch rzeczy: katalogu danych Gitea (/var/lib/gitea przy domyślnej instalacji natywnej) oraz bazy danych. Jeśli Twoją bazą jest SQLite, ten plik znajduje się w katalogu danych; jeśli to PostgreSQL lub MySQL, zrzuć ją osobno za pomocą pg_dump lub mysqldump. Migracja bez zweryfikowanej kopii zapasowej to nie migracja, to hazard.

Będziesz też potrzebować:

• Twoja obecna wersja Gitea. Uruchom gitea --version (lub docker exec <container> gitea --version. Ten numer decyduje o całej Twojej ścieżce.
• Twój typ bazy danych: SQLite, PostgreSQL lub MySQL. Niektóre obejścia są specyficzne dla danej bazy danych.
• Dostęp root lub sudo na serwerze.
• Świadomość, że wspierana ścieżka instaluje Forgejo v10.0 jako etap pośredni. Forgejo v10.0 ma status EOL od 16 kwietnia 2025 roku. Instalujesz ją tylko na czas trwania migracji i natychmiast aktualizujesz ją do nowszej wersji.

Dlaczego ścieżka bezpośredniej aktualizacji przestała działać

W grudniu 2024 roku projekt Forgejo opublikował oświadczeniu o zgodności wyznaczyło wyraźną granicę: "Przyszłe wersje Forgejo nie będą wspierać aktualizacji z instancji Gitea działających w wersji v1.23 lub nowszej". To zdanie zawiera cały problem w jednej linii.

Gdy na początku 2024 roku Forgejo powstało jako fork Gitea, oba kody źródłowe zaczęły się coraz bardziej różnić, a schematy baz danych zaczęły się rozjeżdżać. Forgejo utrzymywało okno zgodności, aby dotychczasowi operatorzy Gitea mogli przenieść się na Forgejo, ale to okno miało swój koniec. Forgejo v10.0, wydane 16 stycznia 2025 roku, było "the last version to allow a transparent upgrade from Gitea v1.22 or lower." Nic nowszego niż v10.0 nie odczyta bezpośrednio bazy danych Gitea.

To właśnie moment w czasie zaskakuje ludzi. Gitea v1.23 zostało wydane pod koniec 2024 roku, a bieżące wydanie Gitea na czerwiec 2026 to v1.26.4. Jeśli utrzymywałeś swoją instancję Gitea w miarę aktualną, jesteś już po progu i standardowe samouczki nie opisują już Twojej sytuacji.

Wniosek z sekcji: wspierana ścieżka bezpośrednia kończy się na Gitea v1.22. Wszystko nowsze wymaga dodatkowego kroku.

Znajdź swoją ścieżkę migracji według wersji Gitea

Uruchom gitea --version, znajdź swój wiersz i podążaj ścieżką z trzeciej kolumny. Cała reszta tego przewodnika to szczegóły stojące za tymi wierszami.

Oświadczenia o zgodności wersji pochodzą bezpośrednio z oficjalne ogłoszenie o zgodności Forgejo: Gitea do wersji v1.21 może przejść na Forgejo od v7.0 do v10.0, a Gitea v1.22 może przejść na Forgejo od v8.0 do v10.0. Obie ścieżki kończą się na v10.0 jako ostatnim wspieranym bezpośrednim celu.

Pod pytaniem o wersję kryją się trzy strategie migracji i warto je poznać, zanim przejdziesz do instrukcji krok po kroku:

• Na miejscu, ten sam serwer. Podmień plik binarny lub obraz kontenera na istniejącej maszynie. Najmniej wysiłku, gdy twoja wersja to obsługuje; wymaga pośredniego kroku przez v10.0.
• Przygotowanie na świeżym serwerze. Przygotuj nowy serwer i użyj go jako bezpiecznego celu dla metody migracji odpowiadającej twojej wersji Gitea. Chroni to oryginalny serwer Gitea i ułatwia wycofanie zmian, ale nie omija problemu ze schematem bazy danych w Gitea 1.23+.
• Migracja repo/API. Użyj narzędzi migracyjnych Forgejo, aby pobrać repozytoria ze starej instancji Gitea. Historia git jest częścią niezawodną; metadane, takie jak zgłoszenia, PR-y, etykiety, wydania, dane wiki i komentarze, należy traktować jako działanie best-effort i weryfikować repozytorium po repozytorium.

Wspierana ścieżka: Gitea v1.22 lub starsza

Jeśli używasz Gitea v1.22 lub wcześniejszej, oficjalna dokumentacja migracji opisują dwuetapową ścieżkę: migrację do Forgejo v10.0.x, a następnie aktualizację Forgejo v10 do bieżącego wydania. Pierwszy krok to bezpośrednia podmiana, ponieważ Forgejo v10.x odczytuje bazę danych z Gitea v1.22; drugi krok to zwykła aktualizacja Forgejo.

Istnieją dwa sposoby, aby to zrobić, w zależności od tego, jak Gitea działa na twoim serwerze. Wybierz ten, który pasuje do twojej istniejącej konfiguracji. Jeśli Gitea działa jako usługa systemowa, użyj ścieżki natywnej. Jeśli Gitea działa w kontenerze, użyj ścieżki Docker. Forgejo v10.x działa jako bezpośredni zamiennik dla Gitea v1.22.x.

Ścieżka natywna (systemd)

Najpierw zrób kopię zapasową. Następnie zainstaluj Forgejo v10.0.x, korzystając z pakietu dystrybucji lub binarki wydania przypiętej do v10.0. Zatrzymaj Gitea, zanim cokolwiek skopiujesz. Działająca usługa zapisująca do katalogu danych w trakcie kopiowania uszkodzi kopię.

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

Skopiuj plik konfiguracyjny oraz katalog danych do lokalizacji Forgejo, a następnie popraw właściciela. Plik konfiguracyjny musi być odczytywalny dla grupy forgejo; dane muszą należeć do użytkownika forgejo.

# 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

Uruchom Forgejo i włącz jego autostart.

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

Zanim zaktualizujesz z v10.0, opróżnij kolejki, aby żadna trwająca praca nie została utracona podczas skoku wersji.

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

Teraz zaktualizuj Forgejo v10.0.x do bieżącego wydania, zastępując binarkę wersją v15 i ponownie uruchamiając usługę, zgodnie ze standardowym Przewodnik aktualizacji Forgejo. Po obu krokach uruchom doctor, aby sprawdzić bazę danych i naprawić to, co się da.

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

Przeczytaj /tmp/doctor.log przed zastosowaniem jakiejkolwiek automatycznej naprawy. Użyj --fix tylko wtedy, gdy wynik narzędzia diagnostycznego wskazuje konkretną naprawę, którą rozumiesz, lub gdy podążasz za oficjalną ścieżką rozwiązywania problemów.

Jeśli doctor nie zgłasza krytycznych błędów, a interfejs webowy wyświetla Twoje repozytoria, pierwsza migracja jest zakończona.

Ścieżka Docker / kontenerowa

Jeśli Gitea działała jako kontener, uruchom Forgejo w ten sam sposób. Użyj obrazu Forgejo v10.x jako bezpośredniego zamiennika obrazu Gitea v1.22.x, wskazując go na ten sam wolumin danych i bazę danych. Najpierw upewnij się, że Twoja wersja Docker to co najmniej 20.10.6. Starsze wersje powodują nieokreślone zachowanie z kontenerami Forgejo.

Jeden szczegół specyficzny dla kontenerów, o który potykają się ludzie: zmienne środowiskowe. Forgejo zachowuje prefiks GITEA_ dla zgodności, ale dokumentacja zaleca przekazywanie obu prefiksów, aby twoja konfiguracja przetrwała przyszłą wersję Forgejo, która porzuci stare nazwy.

# 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

W przypadku kontenerów rootless dane muszą należeć do użytkownika 1000 i grupy 1000, zgodnie z użytkownikiem uruchomieniowym obrazu rootless. Po uruchomieniu kontenera na v10.x uruchom to samo forgejo doctor check --all z wnętrza kontenera, a następnie zaktualizuj tag obrazu do bieżącego wydania v15 i uruchom ponownie.

Jeśli używasz Gitea v1.23 lub nowszej

Tutaj kończą się standardowe poradniki, a jednocześnie tutaj znajduje się większość obecnych instalacji. Nie istnieje oficjalnie wspierana bezpośrednia ścieżka z Gitea v1.23+, więc każda poniższa opcja pochodzi od społeczności albo wiąże się z utratą danych. Zanim uruchomisz którąkolwiek z nich, wykonaj pełną kopię zapasową katalogu danych i bazy danych oraz potwierdź, że możesz ją przywrócić. Te metody modyfikują dane produkcyjne; kopia zapasowa to twoja jedyna droga odwrotu.

Te trzy opcje różnią się ryzykiem i tym, ile zachowują. Wybierz tę, której kompromis możesz zaakceptować.

Opcja A: obniżenie wersji schematu SQL / łatka wersji

Najwęższe obejście polega na obniżeniu wersji schematu bazy danych tak, by Forgejo v10 traktowało ją jak bazę z v1.22.

Uwaga: nie traktuj aktualizacji numeru wersji jako kompletnego obniżenia wersji samego w sobie. Zapisana wersja migracji i faktyczny schemat muszą się zgadzać. Na Gitea 1.23.x najpierw przetestuj pełne obniżenie wersji na kopii i porównaj schemat, zanim skierujesz na nią Forgejo.

Osoba opiekująca się Forgejo opisała SQL w Zgłoszenie Codeberg #7638:

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

Po tym kroku podążasz wspieraną ścieżką, tak jakbyś był na v1.22. Kluczowe zastrzeżenie: opiekun potwierdził to konkretnie tylko dla Gitea v1.23.1, nie dla całej gałęzi v1.23.x. Numer wersji schematu jest dokładny; zastosowanie niewłaściwej wartości docelowej do niewłaściwego wydania Gitea może pozostawić bazę danych w stanie, z którego żadna migracja nie jest w stanie jej odzyskać. Dotyczy to PostgreSQL/MySQL, nie jest to oficjalnie wspierane i nie zostało przetestowane jako procedura ogólna.

Wskazówka: bezpośrednie ustawienie version=305 pomija migrację 304->305, która zmieniła sposób kodowania sekretów TOTP. Zgłoszenie Codeberg #8210 dokumentuje, że powoduje to uszkodzenie uwierzytelniania dwuskładnikowego u dotkniętych użytkowników. Naprawą jest ustawienie wersji na 304 i pozwolenie migracji na przebiegnięcie, lub wyczyszczenie wierszy tabeli two_factor, aby użytkownicy zarejestrowali się ponownie. Nie pomijaj tego, jeśli jakiekolwiek konto używa TOTP.

Opcja B: sekwencyjne skrypty obniżające wersję SQL (Gitea 1.24-1.25.2)

Dla wersji pomiędzy 1.24 a 1.25.2 pojedyncza łatka wersji nie wystarczy: schemat przeszedł przez kilka stanów pośrednich. Skrypty społecznościowe pod adresem xlrl/prepare-gitea-migration-to-forgejo cofają schemat przez pośrednie wersje aż do v1.22, po czym korzystasz ze wspieranej ścieżki. Te skrypty to praca społeczności, nie autorytatywna procedura, i są ukierunkowane głównie na SQLite. Uruchamiaj je wyłącznie na bazie danych, którą już zabezpieczyłeś kopią zapasową.

Opcja C: migracja przez API repozytorium po repozytorium (Gitea 1.26+ lub dowolna wersja)

Ścieżka repo/API najbardziej niezawodnie zachowuje dane Git. W zależności od źródła, uprawnień i metody migracji, dostępne mogą być również opcjonalne metadane, takie jak zgłoszenia, pull requesty, etykiety, kamienie milowe, wydania, dane wiki i komentarze, ale traktuj je jako działanie best-effort i weryfikuj repozytorium po repozytorium. Dla archiwum zawierającego tylko kod to zwykle wystarcza; dla serwera, na którym tracker zgłoszeń stanowi pamięć zespołu, przetestuj transfer metadanych, zanim zdecydujesz się na tę ścieżkę.

Dwa eksperymentalne narzędzia próbują pełniejszej migracji dla 1.23+, ale mają własne luki. pacnpal/gitea2forgejo (GitHub) wykonuje pełny zrzut danych oraz synchronizację przez API i wymaga zgodnego SECRET_KEY, aby przenieść zaszyfrowane pola, ale nie przenosi Personal Access Tokens, runnerów Actions, adresów URL callback webhooków ani 2FA. nicoverbruggen/gitea-to-forgejo (GitHub) to eksperymentalne narzędzie oparte na Podman, które przenosi użytkowników, klucze, organizacje, repozytoria, issues, PR-y, wydania i mirrory, ale nie tokeny 2FA, dane środowiska uruchomieniowego Actions ani nieprzypisane manifesty pakietów OCI. Traktuj oba narzędzia jako eksperymentalne i zweryfikuj wynik według macierzy transferu poniżej.

Wniosek z sekcji: nie istnieje oficjalnie wspierana bezpośrednia ścieżka z Gitea 1.23+. Wybierz opcję, z której kompromisem w postaci utraty danych możesz żyć, i zrób kopię zapasową, zanim zaczniesz.

Migracja na świeżym serwerze jest bezpieczniejsza, ale nie omija progu wersji

Świeży serwer to najbezpieczniejsze miejsce do przygotowania i zweryfikowania migracji, ale nie jest to osobna ścieżka zgodności schematu. Jeśli Twoim źródłem jest Gitea v1.22 lub wcześniejsza, zainstaluj najpierw Forgejo v10.0.x na docelowym serwerze, przywróć lub skopiuj tam dane Gitea, pozwól Forgejo wykonać wspierane migracje bazy danych, a następnie zaktualizuj tę instancję Forgejo v10 do bieżącego wydania Forgejo.

Jeśli Twoim źródłem jest Gitea v1.23 lub nowsza, nie przywracaj bazy danych Gitea bezpośrednio do bieżącej Forgejo, oczekując, że po prostu ruszy. Nadal potrzebujesz jednego z niewspieranych podejść dla 1.23+ opisanych powyżej: etapowego obniżenia wersji SQL lub cofnięcia, narzędzia migracyjnego społeczności, lub migracji przez repo/API. Świeży serwer zmniejsza ryzyko wycofania zmian, ponieważ oryginalna maszyna z Gitea pozostaje nietknięta; nie eliminuje jednak potrzeby obsłużenia niezgodności wersji bazy danych.

Tutaj właśnie Instalowana jednym kliknięciem Forgejo od Cloudzy aplikacja Cloudzy może pomóc: użyj jej jako czystej instancji docelowej, a następnie uruchom metodę migracji odpowiadającą twojej wersji Gitea. Obraz z marketplace Cloudzy daje ci gotowy cel Forgejo na naszym wydajnym VPS, dzięki czemu możesz skupić się na przywracaniu, weryfikacji i przełączeniu, zamiast na wstępnej instalacji. Plan migracji nadal zależy od tego, czy jesteś przed, czy po progu Gitea 1.22.

Co się przenosi, a co musisz zrobić od nowa

Część danych przenosi się automatycznie, część tylko wtedy, gdy spełniony jest określony warunek, a część nigdy się nie przenosi i trzeba ją odtworzyć ręcznie. Wiedza o tym, co jest czym, zanim zaczniesz, to różnica między czystym przełączeniem a tygodniem zdezorientowanych użytkowników.

Cztery elementy uderzają najmocniej, ponieważ psują się po cichu lub dotyczą każdego użytkownika, więc zajmij się nimi świadomie: użytkownicy powinni odtworzyć lub zweryfikować swoje Personal Access Tokens, musisz ponownie zarejestrować swoje runnery Actions pod nową nazwą hosta, musisz usunąć indeks wyszukiwania Bleve, aby Forgejo odbudowało go od nowa, oraz musisz przepisać wszelkie uses: krótkie odwołania w twoich workflowach Actions na pełne adresy URL GitHub, ponieważ Forgejo i Gitea pobierają akcje z osobnych mirrorów, a odwołanie względne wskazuje na niewłaściwe miejsce.

Wskazówka: jeśli podczas migracji uruchamiasz Gitea i Forgejo równolegle, a oba wskazują na tę samą instancję Redis, zmień Forgejo na Redis db=1, zanim zaczniesz. Domyślnie oba używają db=0, a jeśli je współdzielą, Gitea pochłania zdarzenia migracji Forgejo i niszczy kolejkę migracji. (blog.mei-home.net documents this exact failure.)

Wniosek z sekcji: Personal Access Tokens, runnery Actions, klucze wdrożeniowe per repozytorium oraz indeks wyszukiwania Bleve zawsze wymagają ręcznej obsługi. Zaplanuj je jako zadania migracyjne, a nie coś na później.

Zweryfikuj, że migracja się powiodła

Zacznij od narzędzia diagnostycznego, potem sprawdź liczby, a następnie przetestuj rzeczy, które faktycznie robią użytkownicy. Narzędzie diagnostyczne wychwytuje problemy na poziomie bazy danych; ręczne kontrole wychwytują problemy z utratą danych i dostępem, których narzędzie diagnostyczne nie widzi.

1. Uruchom forgejo doctor check --all --log-file /tmp/doctor.log, a następnie przeczytaj log przed wprowadzeniem zmian. Użyj --fix tylko dla konkretnej naprawy, którą rozumiesz.
2. Sprawdź, czy liczba repozytoriów, liczba issues i PR-ów oraz liczba i całkowity rozmiar obiektów LFS zgadzają się z Twoimi liczbami sprzed migracji. Rozbieżność tutaj oznacza, że coś nie zostało przeniesione.
3. Przetestuj push i pull przez SSH. Jeśli klienci dostają błąd niezgodności klucza hosta, nie skopiowałeś /etc/ssh/ssh_host_* na nowy serwer.
4. Zaloguj się i potwierdź, że 2FA działa dla konta, które z niego korzysta. Jeśli TOTP jest uszkodzone, zobacz zastrzeżenie dotyczące Opcji A powyżej.
5. Wygeneruj ponownie Personal Access Tokens, zarejestruj ponownie runnery Actions i uruchom testowy workflow.

Kilka objawów pojawiających się po migracji ma znane przyczyny. Brakująca favicona lub logo oznacza, że zasoby brandingowe wciąż znajdują się w public/assets/img/ zamiast w custom/, gdzie oczekuje ich teraz Forgejo. Błędy 404 na trasach pakietów wskazują na źle skonfigurowane ścieżki przechowywania. Błąd Actions z komunikatem "repository not found" to uses: problem z mirrorem. Przełącz się na pełne adresy URL. Pusta strona lub błąd 500 po zalogowaniu przy bazie danych SQLite oznacza, że jesteś poniżej minimum, co dokumentacji aktualizacji ustaliło na Forgejo v1.19.3-0.

Kiedy warto zostać przy Gitea

Migracja to wybór, nie obowiązek. Jeśli jesteś już po progu wersji, a złożoność migracji przewyższa korzyści związane z zarządzaniem lub funkcjami w Twojej sytuacji, pozostanie przy Gitea jest uzasadnionym wyborem. Gitea jest aktywnie rozwijana (wiele wydań miesięcznie, obecnie na v1.26.4), a CommitGo oferuje opcje komercyjne, w tym Gitea Enterprise, Gitea Cloud oraz certyfikację SOC 2 Type 2 dla zespołów, które ich potrzebują.

Trzeba też uczciwie rozważyć kwestię pośredniej wersji EOL. Wspierana ścieżka bezpośrednia wymaga chwilowej instalacji Forgejo v10.0, które jest w stanie EOL od kwietnia 2025 roku. Jest to akceptowalne jako przejściowy krok migracji, z którego natychmiast się aktualizujesz, ale niektórzy administratorzy będą mieli zastrzeżenia z powodów politycznych. Dla nich migracja repo/API do świeżej instancji Forgejo może całkowicie ominąć krok EOL, podczas gdy stawianie na nowym serwerze wciąż zależy od wybranej metody migracji.

Jeśli Twoim powodem przejścia jest aktywność deweloperska, dane wskazują na Forgejo jako bardziej aktywny projekt: analiza przeprowadzona przez honeypot.net naliczono 3039 commitów Forgejo wobec 1228 commitów Gitea w okresie od lipca 2024 do maja 2025 roku, oraz 232 współtwórców Forgejo wobec 153 dla Gitea w roku kończącym się w maju 2025. To jeden sygnał wśród wielu; rozważ go w kontekście ryzyka migracji, zamiast traktować jako rozstrzygający.

Wniosek z sekcji: migracja nie jest obowiązkowa. To decyzja oparta na preferencjach dotyczących zarządzania i aktywności projektu, ważona względem ryzyka migracji, i obydwa wybory są uzasadnione.

Wybierz swoją ścieżkę i najpierw zrób kopię zapasową

Twoja ścieżka migracji sprowadza się do jednej liczby: twojej wersji Gitea. Na v1.22 lub starszej korzystasz ze wspieranej dwuetapowej ścieżki przez Forgejo v10. Na v1.23 lub nowszej wybierasz obejście według poziomu utraty danych, na jaki możesz sobie pozwolić: obniżenie wersji SQL/schematu, skrypty społecznościowe, migrację repo/API lub migrację na nowym, przygotowanym serwerze. Bez względu na to, którą ścieżkę wybierzesz, najpierw zrób kopię zapasową katalogu danych i bazy danych, uruchom forgejo doctor potem, i potwierdź, że liczba repozytoriów, zgłoszeń i obiektów LFS zgadza się z tym, od czego zaczynałeś.

Zidentyfikuj swoją wersję, zrób kopię zapasową i podążaj odpowiednim wierszem. Ścieżka jest bardziej złożona niż obiecywały stare samouczki, ale jest dobrze zdefiniowana, gdy już wiesz, gdzie znajdujesz się względem progu wersji.

Często zadawane pytania

Czy mogę zaktualizować bezpośrednio z Gitea do Forgejo?

Tak, jeśli używasz Gitea v1.22 lub starszej: zaktualizuj bezpośrednio do Forgejo v10.0, a następnie zaktualizuj Forgejo v10 do bieżącego wydania. Nie, jeśli używasz Gitea v1.23 lub nowszej. Forgejo v10.0 było ostatnim wydaniem wspierającym przezroczystą bezpośrednią aktualizację, więc nowsze wersje Gitea wymagają zamiast tego obejścia.

Z jaką wersją Gitea kompatybilne jest Forgejo?

Gitea v1.22 i wcześniejsze mają wspieraną bezpośrednią ścieżkę aktualizacji do Forgejo (do Forgejo v10.0, a następnie dalej do bieżącej wersji). Gitea v1.23 i nowsze nie mają oficjalnie wspieranej ścieżki bezpośredniej, ponieważ Forgejo przestało wspierać bezproblemowe aktualizacje z Gitea v1.23+ od wydań po v10.0.

Czy mogę migrować z Gitea 1.26 do Forgejo?

Tak, ale nie przez wspieraną bezpośrednią aktualizację. Twoje opcje to migracja repo/API, w której historia git jest częścią niezawodną, a metadane trzeba testować repozytorium po repozytorium, eksperymentalny skrypt migracyjny, lub migracja na nowym serwerze przy użyciu jednej z niewspieranych metod dla 1.23+ opisanych powyżej. Nie istnieje oficjalnie wspierana ścieżka aktualizacji w miejscu z Gitea 1.26.

Czy moje Personal Access Tokens zostaną przeniesione?

Zaplanuj odtworzenie lub rotację Personal Access Tokens po migracji. Niektóre ścieżki migracji ich nie zachowują, a nawet jeśli tokeny pozostają obecne, użytkownicy powinni sprawdzić ich zakresy uprawnień, zanim znów zaczną na nich polegać. Wszelkie skrypty lub integracje korzystające ze starych tokenów należy przetestować i zaktualizować po przełączeniu.

Czy moje workflowy Gitea Actions będą działać w Forgejo?

W większości tak, z dwiema wymaganymi poprawkami. Workflow uses: krótkie odwołania przestają działać, ponieważ Forgejo i Gitea pobierają akcje z osobnych mirrorów. Zamień je na pełne adresy URL GitHub (na przykład, uses: https://github.com/sammcj/dotenv-output-action@main. Musisz też ponownie zarejestrować swoje runnery Actions, ponieważ ich tokeny rejestracyjne są powiązane ze starą nazwą hosta.

A co z migracją z Gogs do Forgejo?

To zupełnie inna migracja, z inną ścieżką, i wykracza poza zakres tego tekstu. Ten poradnik dotyczy konkretnie migracji z Gitea do Forgejo; jeśli źródłem jest Gogs, sięgnij po oficjalną dokumentację migracji Forgejo dotyczącą procedury specyficznej dla Gogs.