Sådan migrerer du fra Gitea til Forgejo uden at ødelægge dine repositories

Du stopper Gitea, installerer Forgejo, kopierer app.ini og din datamappe, og starter tjenesten, som alle migreringsguides beskriver. Web-UI'et kommer op. Så fejler databasemigreringen, eller værre, Forgejo nægter at starte, fordi din skemaversion er for ny til, at den kan forstå den. Du kører Gitea 1.23 eller nyere, og den simple in-place-opgradering, som alle dokumenterer, gælder ikke længere for dig.

Forgejo blev en hard fork af Gitea i begyndelsen af 2024, og de to projekter er siden divergeret på databaseskemaniveau. Hvordan du migrerer Gitea til Forgejo, afhænger nu helt af din Gitea-version. Denne guide giver dig den præcise vej for din version, de fuldstændige kommandoer til både native og Docker-installationer, workarounds til Gitea 1.23+ og en verificeringstjekliste, så du migrerer uden at miste repositories, issues eller brugere.

TL;DR

• Versionsklippen er reel. Forgejo v10.0 var den sidste udgivelse, der understøttede en transparent direkte opgradering fra Gitea. Gitea v1.22 er den højeste version, der kan følge den understøttede direkte vej.
• På Gitea v1.22 eller tidligere: migrér først til Forgejo v10.0.x, opgradér derefter Forgejo v10 til den aktuelle udgivelse (v15). To trin, begge understøttet.
• På Gitea v1.23 eller nyere: findes der ingen officielt understøttet direkte vej. Du vælger mellem en SQL/skema-nedgradering, community-migreringsscripts, repo/API-migrering eller en fresh-server-staging-migrering ved hjælp af en af disse metoder. Hver af dem indebærer et andet kompromis omkring datatab.
• Tag backup af din datamappe og din database, før du rører ved noget. Hver vej nedenfor forudsætter, at du har en gendannelig backup. De uofficielle veje forudsætter det dobbelt så meget.
• Nogle ting kræver altid opmærksomhed efter migreringen: planlæg at genskabe eller gennemgå Personal Access Tokens, genregistrér Actions-runnere, og slet og genopbyg Bleve-søgeindekset. Planlæg med disse uanset hvilken vej du vælger.
• At migrere er ikke obligatorisk. Gitea vedligeholdes aktivt. Beslutningen om at "blive på Gitea" holder, hvis migreringsrisikoen opvejer fordelen i din situation.

Uden for denne guides fokus: migrering fra Gogs, GitHub eller GitLab til Forgejo, samt opsætning af Forgejo Actions fra bunden.

Forudsætninger / hvad du skal bruge

Før du kører en eneste kommando, skal du bekræfte, at du har en fuld, gendannelig backup af to ting: din Gitea-datamappe (/var/lib/gitea ved en standard native installation) og din database. Hvis din database er SQLite, ligger den fil inde i datamappen; hvis det er PostgreSQL eller MySQL, skal du dumpe den separat med pg_dump eller mysqldump. En migrering uden en verificeret backup er ikke en migrering, det er et gamble.

Du får også brug for:

• Din nuværende Gitea-version. Kør gitea --version (eller docker exec <container> gitea --version). Dette tal afgør hele din vej.
• Din databasetype: SQLite, PostgreSQL eller MySQL. Nogle løsninger er databasespecifikke.
• Root- eller sudo-adgang på serveren.
• En bevidsthed om, at den understøttede vej installerer Forgejo v10.0 som et mellemtrin. Forgejo v10.0 har været EOL siden 16. april 2025. Du installerer den kun i løbet af migreringen og opgraderer væk fra den med det samme.

Hvorfor den direkte opgraderingsvej gik i stykker

I december 2024 udgav Forgejo-projektet en kompatibilitetserklæring der trak en klar streg i sandet: "Fremtidige Forgejo-versioner vil ikke understøtte opgraderinger fra Gitea-instanser, der kører version v1.23 eller nyere." Den sætning er hele problemet i én linje.

Da Forgejo forkede fra Gitea i starten af 2024, blev de to kodebaser ved med at bevæge sig fra hinanden, og databaseskemaerne drev fra hinanden. Forgejo opretholdt et kompatibilitetsvindue, så eksisterende Gitea-driftsansvarlige kunne skifte over, men det vindue havde en ende. Forgejo v10.0, udgivet den 16. januar 2025, var "the last version to allow a transparent upgrade from Gitea v1.22 or lower." Alt nyere end v10.0 kan ikke læse en Gitea-database direkte.

Det er timingen, der fanger folk. Gitea v1.23 udkom i slutningen af 2024, og den aktuelle Gitea-udgivelse pr. juni 2026 er v1.26.4. Hvis du har holdt din Gitea-instans nogenlunde opdateret, er du allerede forbi skellet, og de almindelige tutorials beskriver ikke længere din situation.

Opsummering: den understøttede direkte vej stopper ved Gitea v1.22. Alt nyere kræver et ekstra trin.

Find din migreringsvej ud fra Gitea-version

Kør gitea --version, find din række, og følg vejen i tredje kolonne. Alt andet i denne guide er detaljerne bag disse rækker.

Versionskompatibilitetserklæringerne kommer direkte fra Forgejos officielle kompatibilitetsmeddelelse: Gitea op til v1.21 kan flyttes til Forgejo v7.0 til v10.0, og Gitea v1.22 kan flyttes til Forgejo v8.0 til v10.0. Begge topper ved v10.0 som det sidste understøttede direkte mål.

Under versionsspørgsmålet ligger der tre migreringsstrategier, og det hjælper at se dem, før du går i gang med trin-for-trin-vejledningerne:

• På stedet, samme server. Udskift den binære fil eller container-image på den eksisterende server. Mindst besvær, når din version understøtter det; kræver mellemtrinnet v10.0.
• Forberedelse på en frisk server. Sæt en ny server op, og brug den som et sikkert mål for den migreringsmetode, der passer til din Gitea-version. Dette beskytter den oprindelige Gitea-server og gør rollback nemmere, men det omgår ikke Gitea 1.23+-databaseskemaproblemet.
• Repo/API-migrering. Brug Forgejos migreringsværktøjer til at hente repositories fra den gamle Gitea-instans. Git-historikken er den pålidelige del; metadata som issues, PR'er, labels, releases, wiki-data og kommentarer bør betragtes som best-effort og verificeres repo for repo.

Den understøttede vej: Gitea v1.22 eller ældre

Hvis du er på Gitea v1.22 eller tidligere, den officiel migreringsdokumentation beskriver en to-trins-vej: migrér til Forgejo v10.0.x, opgradér derefter Forgejo v10 til den aktuelle udgivelse. Det første trin er en direkte ombytning, fordi Forgejo v10.x læser en Gitea v1.22-database; det andet trin er en normal Forgejo-opgradering.

Der er to måder at gøre dette på, afhængigt af hvordan Gitea kører på din server. Vælg den, der passer til din eksisterende opsætning. Hvis Gitea kører som en systemtjeneste, skal du bruge den native vej. Hvis Gitea kører i en container, skal du bruge Docker-vejen. Forgejo v10.x fungerer som en direkte erstatning for Gitea v1.22.x.

Native (systemd)-vej

Tag først en backup. Installer derefter Forgejo v10.0.x med din distributions pakke eller den release-binary, der er fastlåst til v10.0. Stop Gitea, før du kopierer noget. En kørende tjeneste, der skriver til sin datamappe midt i kopieringen, vil ødelægge kopien.

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

Kopier konfigurationen og datamappen til Forgejos placeringer, og ret derefter ejerskabet. Konfigurationsfilen skal kunne læses af gruppen forgejo; dataene skal ejes af brugeren 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

Start Forgejo, og aktivér den ved opstart.

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

Før du opgraderer væk fra v10.0, skal du tømme køerne, så intet igangværende arbejde går tabt under versionsspringet.

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

Opgrader nu Forgejo v10.0.x til den aktuelle udgivelse ved at erstatte binærfilen med v15 og genstarte tjenesten, ved at følge den almindelige Forgejo-opgraderingsguide. Efter begge hop skal du køre doctor for at tjekke databasen og rette det, den kan.

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

Læs /tmp/doctor.log før du anvender en automatisk rettelse. Brug --fix kun når doctor-outputtet identificerer en specifik reparation, du forstår, eller når du følger en officiel fejlfindingsvej.

Hvis doctor ikke rapporterer nogen kritiske fejl, og web-UI'et viser dine repositories, er den første migrering fuldført.

Docker/container-vej

Hvis Gitea kørte som en container, skal Forgejo køre på samme måde. Brug Forgejo v10.x-imaget som en drop-in-erstatning for dit Gitea v1.22.x-image, og peg det på den samme datavolumen og database. Bekræft først, at din Docker-version er mindst 20.10.6. Ældre versioner giver udefineret adfærd med Forgejo-containere.

Den ene container-specifikke detalje, der snubler folk: miljøvariabler. Forgejo bevarer GITEA_-præfikset af hensyn til kompatibilitet, men dokumentationen anbefaler at sende begge præfikser, så din konfiguration overlever en fremtidig Forgejo-version, der dropper de gamle navne.

# 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

For rootless containere skal dataene ejes af bruger 1000 og gruppe 1000, som matcher runtime-brugeren i det rootless image. Når containeren er startet på v10.x, skal du køre den samme forgejo doctor check --all inde fra containeren, opgradér derefter image-tagget til den aktuelle v15-udgivelse, og genstart.

Hvis du er på Gitea v1.23 eller nyere

Det er her, de standard guides stopper, og hvor de fleste nuværende installationer faktisk befinder sig. Der findes ingen officielt understøttet direkte vej væk fra Gitea v1.23+, så alle mulighederne nedenfor er enten community-baserede eller medfører datatab. Før du kører nogen af dem, skal du tage en fuld backup af din datamappe og din database og bekræfte, at du kan gendanne den. Disse fremgangsmåder ændrer produktionsdata; backuppen er din eneste fortryd-knap.

De tre muligheder adskiller sig i risiko og i, hvor meget de bevarer. Vælg den, hvis kompromis du kan acceptere.

Mulighed A: SQL-skemanedgradering / versionsrettelse

Den smalleste løsning nedgraderer databaseskemaets version, så Forgejo v10 behandler den som en v1.22-database.

Bemærk: Betragt ikke versionsopdateringen som en fuldstændig nedgradering i sig selv. Den registrerede migreringsversion og det faktiske skema skal stemme overens. På Gitea 1.23.x skal du først teste den fulde nedgradering på en kopi og sammenligne skemaet, før du peger Forgejo på det.

En Forgejo-vedligeholder beskrev SQL'en i Codeberg issue #7638:

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

Herefter følger du den understøttede vej, som om du var på v1.22. Det kritiske forbehold: vedligeholderen bekræftede kun dette specifikt for Gitea v1.23.1, ikke hele v1.23.x. Skemaversionsnummeret er præcist; hvis du anvender den forkerte målværdi på den forkerte Gitea-udgivelse, kan databasen ende i en tilstand, som ingen migrering kan gendanne fra. Dette gælder PostgreSQL/MySQL, det er ikke officielt understøttet, og det er ikke testet som en generel procedure.

Pro-tip: Hvis du sætter version=305 direkte, springer du 304→305-migreringen over, som ændrede måden, TOTP-hemmeligheder kodes på. Codeberg issue #8210 dokumenterer, at dette ødelægger to-faktor-godkendelse for berørte brugere. Løsningen er at sætte versionen til 304, lade migreringen køre, eller at rydde rækkerne i two_factor-tabellen, så brugerne skal tilmelde sig igen. Spring ikke dette over, hvis nogen konti bruger TOTP.

Mulighed B: Sekventielle SQL-nedgraderingsscripts (Gitea 1.24–1.25.2)

For versioner mellem 1.24 og 1.25.2 er en enkelt versionspatch ikke nok: skemaet gennemgik flere mellemliggende tilstande. Community-scripts på xlrl/prepare-gitea-migration-to-forgejo fører skemaet tilbage gennem mellemversionerne til v1.22, hvorefter du tager den understøttede vej. Disse scripts er community-arbejde, ikke en autoritativ procedure, og de er rettet mod SQLite som det primære tilfælde. Kør dem kun mod en database, du allerede har taget backup af.

Mulighed C: Repo-for-repo API-migrering (Gitea 1.26+ eller enhver version)

Repo/API-vejen bevarer Git-data mest pålideligt. Afhængigt af kilden, rettighederne og migreringsmetoden kan valgfri metadata som issues, pull requests, labels, milestones, releases, wiki-data og kommentarer også være tilgængelige, men betragt dem som best-effort, og verificér dem repo for repo. For et rent kodearkiv er dette som regel fint; for en server, hvor issue trackeren er teamets hukommelse, bør du teste metadataoverførslen, før du binder dig til denne vej.

To eksperimentelle værktøjer forsøger sig med mere fuldstændige migreringer til 1.23+, men har hver deres huller. pacnpal/gitea2forgejo (GitHub) laver en fuld dump plus API-synkronisering og kræver en matchende SECRET_KEY for at krypterede felter kan overføres, men den flytter ikke Personal Access Tokens, Actions runners, webhook-callback-URL'er eller 2FA. nicoverbruggen/gitea-to-forgejo (GitHub) er et Podman-baseret eksperimentelt værktøj, der overfører brugere, nøgler, organisationer, repos, issues, PRs, releases og mirrors, men ikke 2FA-tokens, Actions-runtimedata eller løsrevne OCI-pakkemanifester. Betragt begge som eksperimentelle, og verificer resultatet mod overførselsmatrixen nedenfor.

Opsummering: der findes ingen officielt understøttet direkte vej væk fra Gitea 1.23+. Vælg den mulighed, hvis datatab du kan leve med, og tag backup, før du starter.

At migrere på en frisk server er sikrere, men det omgår ikke versionsskellet

En frisk server er det sikreste sted at forberede og verificere migreringen, men det er ikke en separat vej til skemakompatibilitet. Hvis din kilde er Gitea v1.22 eller ældre, skal du først installere Forgejo v10.0.x på målserveren, gendanne eller kopiere Gitea-dataene dertil, lade Forgejo køre de understøttede databasemigreringer og derefter opgradere den Forgejo v10-instans til den aktuelle Forgejo-udgivelse.

Hvis din kilde er Gitea v1.23 eller nyere, må du ikke gendanne Gitea-databasen direkte i den aktuelle Forgejo og forvente, at den starter. Du har stadig brug for en af de uofficielle 1.23+-fremgangsmåder ovenfor: en trinvis SQL-nedgradering eller tilbagerulning, et community-migreringsværktøj, eller en repo/API-migrering. Den friske server reducerer risikoen ved en tilbagerulning, fordi den oprindelige Gitea-maskine forbliver urørt; den fjerner ikke behovet for at håndtere uoverensstemmelsen i databaseversion.

Her er det, at Cloudzys one-click Forgejo app kan hjælpe: brug den som den rene målinstans, og kør derefter den migreringsmetode, der passer til din Gitea-version. Cloudzys marketplace-image giver dig et klart Forgejo-mål på vores højtydende VPS, så du kan fokusere på gendannelse, verificering og overgangstrin i stedet for den indledende installation. Migreringsplanen afhænger stadig af, om du er før eller efter Gitea 1.22-skellet.

Hvad overføres, og hvad skal du gøre om

Noget af dine data flyttes automatisk, noget flyttes kun, hvis en betingelse er opfyldt, og noget flyttes aldrig og skal genskabes manuelt. At vide, hvad der er hvad, før du starter, er forskellen mellem en ren omstilling og en uge med forvirrede brugere.

Fire ting rammer hårdest, fordi de går i stykker uden varsel eller påvirker alle brugere, så håndter dem bevidst: brugere bør genskabe eller gennemgå deres Personal Access Tokens, du skal gen-registrere dine Actions runners mod det nye hostnavn, du skal slette Bleve-søgeindekset, så Forgejo genopbygger det korrekt, og du skal omskrive enhver uses: korte referencer i dine Actions-workflows til fulde GitHub-URL'er, fordi Forgejo og Gitea henter actions fra separate mirrors, og en relativ reference peger det forkerte sted hen.

Pro-tip: Hvis du kører Gitea og Forgejo parallelt under migreringen, og begge peger på den samme Redis-instans, skal du ændre Forgejo til Redis db=1, før du starter. Begge har som standard db=0, og hvis de deler den, forbruger Gitea Forgejos migreringshændelser og ødelægger migreringskøen. (blog.mei-home.net documents this exact failure.)

Opsummering: Personal Access Tokens, Actions-runnere, deploy keys pr. repo og Bleve-søgeindekset er altid manuelle. Planlæg dem som migreringsopgaver, ikke som eftertanker.

Verificér, at migreringen lykkedes

Start med doctor-kommandoen, tjek derefter tallene, og test til sidst de ting, brugerne faktisk gør. Doctor-kommandoen fanger problemer på databaseniveau; de manuelle tjek fanger de datatabs- og adgangsproblemer, som doctor-kommandoen ikke kan se.

1. Kør forgejo doctor check --all --log-file /tmp/doctor.log, læs derefter loggen, før du foretager ændringer. Brug --fix kun til en specifik reparation, du forstår.
2. Bekræft, at antallet af repositories, antallet af issues og PRs samt antallet af LFS-objekter og den samlede størrelse alle matcher dine tal fra før migreringen. Et misforhold her betyder, at noget ikke er kommet med over.
3. Test et SSH-push og -pull. Hvis klienter får en host-key-uoverensstemmelse, har du ikke kopieret /etc/ssh/ssh_host_* til den nye server.
4. Log ind, og bekræft at 2FA fungerer for en konto, der bruger det. Hvis TOTP er i stykker, se forbeholdet for mulighed A ovenfor.
5. Generér Personal Access Tokens igen, genregistrér Actions-runnere, og kør et testworkflow.

Nogle symptomer efter migreringen har kendte årsager. Et manglende favicon eller logo betyder, at dine branding-assets stadig ligger i public/assets/img/ i stedet for custom/, hvor Forgejo nu forventer dem. 404-fejl på pakkeruter peger på forkert konfigurerede storage-stier. Actions, der fejler med "repository not found", er uses: mirror-problem. Skift til fulde URL'er. En blank side eller en 500-side efter login på en SQLite-database betyder, at du er under minimumskravet, som opgraderingsdokumentation sat til Forgejo v1.19.3-0.

Hvornår det giver mening at blive på Gitea

At migrere er et valg, ikke en forpligtelse. Hvis du allerede er forbi skellet, og kompleksiteten ved migreringen opvejer fordelen ved governance eller funktioner i din situation, er det at blive på Gitea et legitimt valg. Gitea vedligeholdes aktivt (flere udgivelser om måneden, i øjeblikket v1.26.4), og CommitGo tilbyder kommercielle muligheder, herunder Gitea Enterprise, Gitea Cloud og SOC 2 Type 2-certificering til teams, der har brug for dem.

Der er også EOL-mellemtrinnet, som man ærligt bør veje op. Den understøttede direkte vej kræver, at du kortvarigt installerer Forgejo v10.0, som har været EOL siden april 2025. Det er acceptabelt som et forbigående migreringstrin, du opgraderer væk fra med det samme, men nogle driftsansvarlige vil have indvendinger af politiske årsager. For dem kan repo/API-migrering til en ny Forgejo-instans undgå EOL-trinnet helt, mens en fresh-server-staging stadig afhænger af den migreringsmetode, du vælger.

Hvis din grund til at skifte er udviklingsaktivitet, understøtter dataene Forgejo som det mere aktive projekt: en analyse af honeypot.net talte 3,039 Forgejo-commits mod 1,228 Gitea-commits i perioden juli 2024 til maj 2025, og 232 Forgejo-bidragydere mod 153 for Gitea i året frem til maj 2025. Det er ét signal blandt flere; vej det op mod din migreringsrisiko i stedet for at betragte det som afgørende.

Opsummering: migrering er ikke obligatorisk. Beslutningen handler om en præference for governance og aktivitet vejet op mod migreringsrisiko, og begge valg kan forsvares.

Vælg din vej, og tag backup først

Din migreringsvej afhænger af ét tal: din Gitea-version. På v1.22 eller ældre tager du den understøttede to-trins-vej gennem Forgejo v10. På v1.23 eller nyere vælger du en løsning ud fra det datatab, du kan acceptere: SQL/skema-nedgradering, community-scripts, repo/API-migrering eller en fresh-server-staging-migrering. Uanset hvilken vej du vælger, skal du først tage backup af din datamappe og database, kør forgejo doctor bagefter, og bekræft, at dine repository-, issue- og LFS-antal matcher det, du startede med.

Find din version, tag backuppen, og følg den tilsvarende række. Vejen er mere omfattende, end de gamle tutorials lovede, men den er veldefineret, når du først ved, hvor du står i forhold til versionsskellet.

Ofte stillede spørgsmål

Kan jeg opgradere direkte fra Gitea til Forgejo?

Ja, hvis du kører Gitea v1.22 eller ældre: opgradér direkte til Forgejo v10.0, og opgradér derefter Forgejo v10 til den aktuelle udgivelse. Nej, hvis du kører Gitea v1.23 eller nyere. Forgejo v10.0 var den sidste udgivelse, der understøttede en gennemsigtig direkte opgradering, så nyere Gitea-versioner kræver i stedet en løsning.

Hvilken version af Gitea er kompatibel med Forgejo?

Gitea v1.22 og tidligere har en understøttet direkte opgraderingsvej til Forgejo (op til Forgejo v10.0, og derefter videre til den aktuelle). Gitea v1.23 og nyere har ingen officielt understøttet direkte vej, fordi Forgejo stoppede med at understøtte transparente opgraderinger fra Gitea v1.23+ fra og med udgivelser efter v10.0.

Kan jeg migrere fra Gitea 1.26 til Forgejo?

Ja, men ikke gennem en understøttet direkte opgradering. Dine muligheder er en repo/API-migrering, hvor Git-historikken er den pålidelige del, og metadata skal testes repo for repo, et eksperimentelt migreringsscript, eller en fresh-server-staging-migrering ved hjælp af en af de ikke-understøttede 1.23+-metoder ovenfor. Der findes ingen officielt understøttet in-place-vej fra Gitea 1.26.

Overføres mine Personal Access Tokens?

Planlæg at genskabe eller rotere Personal Access Tokens efter migreringen. Nogle migreringsveje bevarer dem ikke, og selv når tokens forbliver til stede, bør brugere gennemgå scopes, før de stoler på dem igen. Alle scripts eller integrationer, der bruger gamle tokens, bør testes og opdateres efter omstillingen.

Virker mine Gitea Actions-workflows i Forgejo?

For det meste, med to nødvendige rettelser. Workflow uses: korte referencer går i stykker, fordi Forgejo og Gitea henter actions fra separate mirrors. Skift dem til fulde GitHub-URL'er (for eksempel uses: https://github.com/sammcj/dotenv-output-action@main). Du skal også gen-registrere dine Actions runners, fordi deres registreringstokens er bundet til det gamle hostnavn.

Hvad med at migrere fra Gogs til Forgejo?

Det er en anden migrering med en anden vej og ligger uden for denne guides fokus. Denne guide dækker specifikt Gitea til Forgejo; hvis din kilde er Gogs, så tjek Forgejos officielle migreringsdokumentation for den Gogs-specifikke fremgangsmåde.