Como migrar do Gitea para o Forgejo sem quebrar seus repositórios

Você para o Gitea, instala o Forgejo, copia o app.ini e seu diretório de dados, e inicia o serviço da forma como todo guia de migração descreve. A UI web sobe. Então a migração do banco de dados falha, ou pior, o Forgejo se recusa a iniciar porque sua versão de schema é recente demais para ele entender. Você está no Gitea 1.23 ou posterior, e o upgrade in-place simples que todo mundo documenta não se aplica mais a você.

O Forgejo se tornou um hard fork do Gitea no início de 2024, e os dois projetos divergiram desde então no nível do schema do banco de dados. Como você migra do Gitea para o Forgejo agora depende inteiramente da sua versão do Gitea. Este guia te dá o caminho exato para a sua versão, os comandos completos para instalações nativas e via Docker, as soluções alternativas para o Gitea 1.23+, e uma checklist de verificação, para que você migre sem perder repositórios, issues ou usuários.

TL;DR

• O precipício de versão é real. O Forgejo v10.0 foi o último release a suportar um upgrade direto e transparente a partir do Gitea. O Gitea v1.22 é a versão mais alta que pode seguir o caminho direto suportado.
• No Gitea v1.22 ou anterior: migre para o Forgejo v10.0.x primeiro, depois atualize o Forgejo v10 para a versão atual (v15). Duas etapas, ambas suportadas.
• No Gitea v1.23 ou mais recente: não há caminho direto oficialmente suportado. Você escolhe entre um downgrade de SQL/schema, scripts de migração da comunidade, migração via repositório/API, ou uma migração de staging em servidor novo usando um desses métodos. Cada um traz um trade-off diferente de perda de dados.
• Faça o backup do seu diretório de dados e do seu banco de dados antes de mexer em qualquer coisa. Todo caminho abaixo pressupõe que você tenha um backup restaurável. Os caminhos não suportados pressupõem isso em dobro.
• Algumas coisas sempre exigem atenção pós-migração: planeje recriar ou auditar os tokens de acesso pessoal, registrar novamente os runners do Actions, e excluir e reconstruir o índice de busca Bleve. Planeje isso independentemente do caminho escolhido.
• Migrar não é obrigatório. O Gitea é mantido ativamente. A decisão de "ficar no Gitea" se sustenta se o risco da migração superar o benefício para a sua situação.

Fora do escopo aqui: migrar de Gogs, GitHub ou GitLab para Forgejo, e configurar o Forgejo Actions do zero.

Pré-requisitos / O Que Você Vai Precisar

Antes de executar um único comando, confirme que você tem um backup completo e restaurável de duas coisas: seu diretório de dados do Gitea (/var/lib/gitea em uma instalação nativa padrão) e seu banco de dados. Se seu banco de dados é SQLite, esse arquivo fica dentro do diretório de dados; se for PostgreSQL ou MySQL, exporte-o separadamente com pg_dump ou mysqldump. Uma migração sem um backup verificado não é uma migração, é uma aposta.

Você também vai precisar de:

• Sua versão atual do Gitea. Execute gitea --version (ou docker exec <container> gitea --version). Esse número define todo o seu caminho.
• Seu tipo de banco de dados: SQLite, PostgreSQL ou MySQL. Algumas soluções alternativas são específicas para cada banco de dados.
• Acesso root ou sudo no servidor.
• A consciência de que o caminho suportado instala o Forgejo v10.0 como um salto intermediário. O Forgejo v10.0 está em EOL desde 16 de abril de 2025. Você o instala apenas durante a migração e faz o upgrade para sair dele imediatamente.

Por Que o Caminho de Upgrade Direto Deixou de Funcionar

Em dezembro de 2024, o projeto Forgejo publicou uma declaração de compatibilidade que traçou uma linha rígida: "Versões futuras do Forgejo não vão suportar upgrades a partir de instâncias do Gitea executando a versão v1.23 ou superior." Essa frase é o problema inteiro em uma única linha.

Quando o Forgejo se separou do Gitea no início de 2024, as duas bases de código continuaram divergindo, e os schemas de banco de dados se afastaram um do outro. O Forgejo manteve uma janela de compatibilidade para que os operadores existentes do Gitea pudessem migrar, mas essa janela teve um fim. O Forgejo v10.0, lançado em 16 de janeiro de 2025, foi "the last version to allow a transparent upgrade from Gitea v1.22 or lower." Qualquer versão mais nova que a v10.0 não consegue ler um banco de dados do Gitea diretamente.

O timing é o que pega as pessoas de surpresa. O Gitea v1.23 foi lançado no final de 2024, e o a versão atual do Gitea em junho de 2026 é a v1.26.4. Se você manteve sua instância do Gitea razoavelmente atualizada, você já passou do penhasco e os tutoriais padrão não descrevem mais a sua situação.

Resumo da seção: o caminho direto suportado vai no máximo até o Gitea v1.22. Tudo mais recente precisa de uma etapa extra.

Encontre seu caminho de migração pela versão do Gitea

Execute gitea --version, encontre sua linha e siga o caminho na terceira coluna. Todo o restante deste guia é o detalhe por trás dessas linhas.

As declarações de compatibilidade de versão vêm diretamente do anúncio oficial de compatibilidade do Forgejo: o Gitea até a v1.21 pode migrar para o Forgejo v7.0 até v10.0, e o Gitea v1.22 pode migrar para o Forgejo v8.0 até v10.0. Ambos têm como limite máximo o v10.0 como o último alvo direto suportado.

Por trás da questão da versão existem três estratégias de migração, e ajuda vê-las antes dos passo a passo:

• No local, no mesmo servidor. Substitua o binário ou a imagem de contêiner na máquina existente. É o menor esforço quando sua versão suporta isso; exige a etapa intermediária pela v10.0.
• Preparação em servidor novo. Provisione um novo servidor e use-o como destino seguro para o método de migração que corresponda à sua versão do Gitea. Isso protege a máquina original do Gitea e facilita o rollback, mas não contorna o problema de schema de banco de dados do Gitea 1.23+.
• Migração via repositório/API. Use as ferramentas de migração do Forgejo para puxar os repositórios da instância antiga do Gitea. O histórico do Git é a parte confiável; metadados como issues, PRs, labels, releases, dados de wiki e comentários devem ser tratados como melhor esforço e verificados repositório por repositório.

O Caminho Suportado: Gitea v1.22 ou Anterior

Se você está no Gitea v1.22 ou anterior, o documentação oficial de migração descrevem um caminho em duas etapas: migrar para o Forgejo v10.0.x e depois atualizar o Forgejo v10 para a versão atual. A primeira etapa é uma substituição direta, pois o Forgejo v10.x lê um banco de dados do Gitea v1.22; a segunda etapa é um upgrade normal do Forgejo.

Há duas formas de fazer isso, dependendo de como o Gitea roda no seu servidor. Escolha a que corresponde à sua configuração atual. Se o Gitea roda como um serviço do sistema, use o caminho nativo. Se o Gitea roda em um contêiner, use o caminho Docker. O Forgejo v10.x atua como um substituto direto do Gitea v1.22.x.

Caminho nativo (systemd)

Faça o backup primeiro. Depois instale o Forgejo v10.0.x usando o pacote da sua distribuição ou o binário de release fixado na v10.0. Pare o Gitea antes de copiar qualquer coisa. Um serviço em execução escrevendo no diretório de dados no meio da cópia vai corromper a cópia.

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

Copie a configuração e o diretório de dados para os locais do Forgejo, depois corrija a propriedade. O arquivo de configuração precisa ter permissão de leitura para o grupo forgejo; os dados precisam pertencer ao usuário 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

Inicie o Forgejo e habilite-o na inicialização do sistema.

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

Antes de sair da v10.0, esvazie as filas para que nenhum trabalho em andamento seja perdido durante o salto de versão.

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

Agora atualize o Forgejo v10.0.x para o release atual substituindo o binário pela v15 e reiniciando o serviço, seguindo o padrão Guia de upgrade do Forgejo. Depois de ambos os saltos, execute o doctor para verificar o banco de dados e corrigir o que for possível.

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

Leia /tmp/doctor.log antes de aplicar qualquer correção automática. Use --fix somente quando a saída do doctor identifica um reparo específico que você compreende, ou quando você está seguindo um caminho oficial de solução de problemas.

Se o doctor não relatar erros críticos e a UI web listar seus repositórios, a primeira migração está completa.

Caminho Docker / Container

Se o Gitea rodava como um container, rode o Forgejo da mesma forma. Use a imagem do Forgejo v10.x como um substituto direto da sua imagem do Gitea v1.22.x, apontando-a para o mesmo volume de dados e banco de dados. Confirme primeiro que sua versão do Docker é pelo menos 20.10.6. Versões mais antigas produzem comportamento indefinido com containers do Forgejo.

O único detalhe específico de contêiner que costuma confundir as pessoas: variáveis de ambiente. O Forgejo mantém o prefixo GITEA_ por compatibilidade, mas a documentação recomenda passar os dois prefixos para que sua configuração sobreviva a uma futura versão do Forgejo que abandone os nomes antigos.

# 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

Para containers rootless, os dados precisam pertencer ao usuário 1000 e ao grupo 1000, correspondendo ao usuário de runtime da imagem rootless. Depois que o container iniciar na v10.x, execute o mesmo forgejo doctor check --all de dentro do contêiner, depois atualize a tag da imagem para a versão atual v15 e reinicie.

Se você está no Gitea v1.23 ou mais recente

É aqui que os guias padrão param e onde a maioria das instalações atuais realmente está. Não há caminho direto oficialmente suportado a partir do Gitea v1.23+, então cada opção abaixo é ou vinda da comunidade ou tem perda de dados. Antes de executar qualquer uma delas, faça um backup completo do seu diretório de dados e do seu banco de dados, e confirme que consegue restaurá-lo. Essas abordagens modificam dados de produção; o backup é seu único "desfazer".

As três opções diferem em risco e em quanto preservam. Escolha aquela cujo trade-off você consegue aceitar.

Opção A: Downgrade do Schema SQL / Patch de Versão

A solução alternativa mais estreita reduz a versão do schema do banco de dados para que o Forgejo v10 o trate como um banco de dados v1.22.

Nota: não trate a atualização de versão como um downgrade completo por si só. A versão de migração registrada e o schema real precisam corresponder. No Gitea 1.23.x, teste o downgrade completo em uma cópia primeiro e compare o schema antes de apontar o Forgejo para ele.

Um mantenedor do Forgejo descreveu o SQL em Codeberg issue #7638:

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

Depois disso, você segue o caminho suportado como se estivesse na v1.22. A ressalva crítica: o mantenedor confirmou isso apenas para o Gitea v1.23.1 especificamente, não para todo o v1.23.x. O número da versão do schema é exato; aplicar o valor de destino errado à versão errada do Gitea pode deixar o banco de dados em um estado que nenhuma migração consegue recuperar. Isso é PostgreSQL/MySQL, não é oficialmente suportado e não é testado como um procedimento geral.

Dica profissional: definir version=305 diretamente pula a migração 304→305, que mudou a forma como os segredos TOTP são codificados. Codeberg issue #8210 documenta que isso corrompe a autenticação de dois fatores para os usuários afetados. A correção é definir a versão como 304, deixar a migração rodar, ou limpar as linhas da tabela two_factor para que os usuários se registrem novamente. Não pule esta etapa se alguma conta usar TOTP.

Opção B: Scripts Sequenciais de Downgrade SQL (Gitea 1.24–1.25.2)

Para versões entre 1.24 e 1.25.2, um único patch de versão não é suficiente: o schema passou por vários estados intermediários. Os scripts da comunidade em xlrl/prepare-gitea-migration-to-forgejo revertem o schema passo a passo pelas versões intermediárias até a v1.22, depois do que você segue o caminho suportado. Esses scripts são trabalho da comunidade, não um procedimento oficial, e têm o SQLite como caso principal. Execute-os apenas em um banco de dados que você já tenha feito backup.

Opção C: Migração via API Repositório por Repositório (Gitea 1.26+ ou Qualquer Versão)

O caminho via repositório/API preserva os dados do Git de forma mais confiável. Dependendo da origem, das permissões e do método de migração, metadados opcionais como issues, pull requests, labels, milestones, releases, dados do wiki e comentários também podem estar disponíveis, mas trate isso como algo de melhor esforço e verifique repositório por repositório. Para um arquivo apenas de código, isso geralmente é suficiente; para um servidor em que o rastreador de issues é a memória da equipe, teste a transferência de metadados antes de se comprometer com esse caminho.

Duas ferramentas experimentais tentam migrações mais completas para o 1.23+, mas carregam suas próprias lacunas. pacnpal/gitea2forgejo (GitHub) faz um dump completo mais sincronização via API e exige um SECRET_KEY correspondente para que os campos criptografados sejam transferidos, mas não move Personal Access Tokens, Actions runners, URLs de callback de webhook ou 2FA. nicoverbruggen/gitea-to-forgejo (GitHub) é uma ferramenta experimental baseada em Podman que transfere usuários, chaves, organizações, repositórios, issues, PRs, releases e mirrors, mas não tokens de 2FA, dados de runtime do Actions ou manifestos de pacotes OCI órfãos. Trate ambas como experimentais e verifique o resultado com a matriz de transferência abaixo.

Resumo da seção: não há caminho direto oficialmente suportado a partir do Gitea 1.23+. Escolha a opção cujo trade-off de perda de dados você consiga aceitar, e faça backup antes de começar.

Migrar em um servidor novo é mais seguro, mas não contorna o penhasco de versão

Um servidor novo é o lugar mais seguro para preparar e verificar a migração, mas não é um caminho separado de compatibilidade de schema. Se sua origem é o Gitea v1.22 ou anterior, instale primeiro o Forgejo v10.0.x no destino, restaure ou copie os dados do Gitea para lá, deixe o Forgejo executar as migrações de banco de dados suportadas e, em seguida, atualize essa instância do Forgejo v10 para a versão atual do Forgejo.

Se sua origem é o Gitea v1.23 ou mais recente, não restaure o banco de dados do Gitea diretamente no Forgejo atual esperando que ele funcione. Você ainda precisa de uma das abordagens não suportadas para 1.23+ mencionadas acima: um downgrade ou reversão de SQL em etapas, uma ferramenta de migração da comunidade, ou uma migração via repositório/API. O servidor novo reduz o risco de rollback porque a máquina original do Gitea permanece intocada; mas não elimina a necessidade de lidar com a incompatibilidade de versão do banco de dados.

É aqui que O Forgejo de um clique da Cloudzy app pode ajudar: use-o como a instância de destino limpa e depois execute o método de migração que corresponde à sua versão do Gitea. A imagem do marketplace da Cloudzy te dá um destino Forgejo pronto em nosso VPS de alto desempenho, para que você possa focar nas etapas de restauração, verificação e corte em vez da instalação inicial. O plano de migração ainda depende de você estar antes ou depois do penhasco do Gitea 1.22.

O Que É Transferido e O Que Você Precisa Refazer

Parte dos seus dados é movida automaticamente, parte só é movida se uma condição for atendida, e parte nunca é movida e precisa ser recriada manualmente. Saber o que é cada coisa antes de começar é a diferença entre uma transição limpa e uma semana de usuários confusos.

Quatro itens atingem com mais força porque quebram silenciosamente ou afetam todos os usuários, então trate-os com cuidado: os usuários devem recriar ou auditar seus Personal Access Tokens, você precisa registrar novamente seus Actions runners com o novo hostname, você precisa excluir o índice de busca do Bleve para que o Forgejo o reconstrua do zero, e você precisa reescrever qualquer uses: referências curtas nos seus workflows do Actions para URLs completas do GitHub, porque Forgejo e Gitea puxam actions de mirrors separados e uma referência relativa se resolve para o lugar errado.

Dica profissional: se você executar Gitea e Forgejo em paralelo durante a migração e ambos apontarem para a mesma instância Redis, mude o Forgejo para Redis db=1 antes de começar. Ambos usam db=0 por padrão e, se compartilharem essa instância, o Gitea consome os eventos de migração do Forgejo e destrói a fila de migração. (blog.mei-home.net documents this exact failure.)

Resumo da seção: tokens de acesso pessoal, runners do Actions, chaves de deploy por repositório e o índice de busca Bleve são sempre manuais. Programe-os como tarefas de migração, não como reflexões tardias.

Verifique se a Migração Foi Bem-Sucedida

Comece pelo doctor, depois verifique os números, depois teste as coisas que os usuários realmente fazem. O doctor detecta problemas em nível de banco de dados; as verificações manuais detectam problemas de perda de dados e de acesso que o doctor não consegue ver.

1. Execute forgejo doctor check --all --log-file /tmp/doctor.log, depois leia o log antes de fazer alterações. Use --fix somente para um reparo específico que você compreende.
2. Confirme se a contagem de repositórios, as contagens de issues e PRs, e a contagem de objetos LFS e o tamanho total correspondem aos seus números pré-migração. Uma incompatibilidade aqui significa que algo não foi transferido.
3. Teste um push e um pull via SSH. Se os clientes receberem um erro de host-key mismatch, você não copiou /etc/ssh/ssh_host_* para o novo servidor.
4. Faça login e confirme que o 2FA funciona para uma conta que o utiliza. Se o TOTP estiver quebrado, veja a ressalva da Opção A acima.
5. Regenere os tokens de acesso pessoal, registre novamente os runners do Actions e execute um workflow de teste.

Alguns sintomas pós-migração têm causas conhecidas. Um favicon ou logo ausente significa que seus assets de marca ainda estão em public/assets/img/ em vez de custom/, onde o Forgejo agora os espera. Erros 404 nas rotas de pacotes indicam caminhos de armazenamento configurados incorretamente. Falhas do Actions com "repository not found" são o uses: problema de mirror. Mude para URLs completas. Uma página em branco ou erro 500 após o login em um banco de dados SQLite significa que você está abaixo do mínimo, o que o documentação de upgrade colocou no Forgejo v1.19.3-0.

Quando Faz Sentido Permanecer no Gitea

Migrar é uma escolha, não uma obrigação. Se você já está além do penhasco e a complexidade da migração supera o benefício de governança ou de recursos para a sua situação, permanecer no Gitea é uma escolha legítima. O Gitea é mantido ativamente (vários releases por mês, atualmente na v1.26.4), e a CommitGo oferece opções comerciais, incluindo Gitea Enterprise, Gitea Cloud, e certificação SOC 2 Type 2 para equipes que precisam deles.

Há também a preocupação com a etapa intermediária em EOL, que precisa ser ponderada com honestidade. O caminho direto suportado exige instalar brevemente o Forgejo v10.0, que está em EOL desde abril de 2025. Isso é aceitável como uma etapa de migração transitória da qual você se afasta imediatamente com um upgrade, mas alguns operadores vão objetar por motivos de política. Para eles, a migração via repositório/API para uma instância nova do Forgejo pode evitar totalmente essa etapa em EOL, enquanto o staging em servidor novo ainda depende do método de migração escolhido.

Se o seu motivo para migrar é a atividade de desenvolvimento, os dados apoiam o Forgejo como o projeto mais ativo: uma análise de honeypot.net contou 3.039 commits do Forgejo contra 1.228 commits do Gitea entre julho de 2024 e maio de 2025, e 232 contribuidores do Forgejo contra 153 do Gitea no ano encerrado em maio de 2025. Esse é apenas um sinal entre vários; pondere-o em relação ao risco da sua migração, em vez de tratá-lo como decisivo.

Resumo da seção: migrar não é obrigatório. A decisão é uma preferência de governança e atividade ponderada contra o risco da migração, e ambas as escolhas são defensáveis.

Escolha Seu Caminho e Faça Backup Primeiro

Seu caminho de migração se resume a um número: sua versão do Gitea. Na v1.22 ou anterior, você segue o caminho suportado em duas etapas através do Forgejo v10. Na v1.23 ou mais recente, você escolhe uma solução alternativa pela perda de dados que consegue aceitar: downgrade de SQL/schema, scripts da comunidade, migração via repositório/API, ou uma migração de staging em servidor novo. Seja qual for o caminho escolhido, faça backup do seu diretório de dados e do banco de dados primeiro, execute forgejo doctor depois, e confirme que as contagens de repositórios, issues e LFS correspondem ao que você tinha no início.

Identifique sua versão, faça o backup e siga a linha correspondente. O caminho é mais elaborado do que os tutoriais antigos prometiam, mas é bem definido assim que você sabe onde está em relação ao penhasco de versões.

Perguntas frequentes

Posso atualizar diretamente do Gitea para o Forgejo?

Sim, se você roda o Gitea v1.22 ou anterior: atualize diretamente para o Forgejo v10.0 e depois atualize o Forgejo v10 para a versão atual. Não, se você roda o Gitea v1.23 ou mais recente. O Forgejo v10.0 foi o último lançamento com suporte a um upgrade direto transparente, então versões mais recentes do Gitea precisam de uma solução alternativa.

Qual Versão do Gitea É Compatível com o Forgejo?

O Gitea v1.22 e versões anteriores têm um caminho de upgrade direto suportado para o Forgejo (até o Forgejo v10.0, e depois seguindo até a versão atual). O Gitea v1.23 e versões mais novas não têm um caminho direto oficialmente suportado, porque o Forgejo parou de suportar upgrades transparentes a partir do Gitea v1.23+ nos releases posteriores ao v10.0.

Posso migrar do Gitea 1.26 para o Forgejo?

Sim, mas não por meio de um upgrade direto suportado. Suas opções são uma migração via repositório/API, em que o histórico do Git é a parte confiável e os metadados precisam ser testados repositório por repositório, um script de migração experimental, ou uma migração de staging em servidor novo usando um dos métodos não suportados para 1.23+ mencionados acima. Não há caminho in-place oficialmente suportado a partir do Gitea 1.26.

Meus Personal Access Tokens são transferidos?

Planeje recriar ou rotacionar os tokens de acesso pessoal após a migração. Alguns caminhos de migração não os preservam e, mesmo quando os tokens permanecem presentes, os usuários devem auditar os escopos antes de voltar a confiar neles. Quaisquer scripts ou integrações que usem tokens antigos devem ser testados e atualizados após a transição.

Meus workflows do Gitea Actions funcionam no Forgejo?

Na maior parte, com duas correções necessárias. O workflow uses: referências curtas quebram porque Forgejo e Gitea puxam actions de mirrors separados. Troque-as por URLs completas do GitHub (por exemplo, uses: https://github.com/sammcj/dotenv-output-action@main). Você também precisa registrar novamente seus Actions runners, porque os tokens de registro estão vinculados ao hostname antigo.

E Quanto à Migração de Gogs para Forgejo?

Essa é uma migração diferente, com um caminho diferente, e está fora do escopo aqui. Este guia cobre especificamente Gitea para Forgejo; para uma origem em Gogs, consulte a documentação oficial de migração do Forgejo para o procedimento específico do Gogs.