Como hospedar o Gitea por conta própria em 2026: repositórios, SSH e segurança nas atualizações

Se você já tentou hospedar o Gitea por conta própria, provavelmente conhece este estado frustrante: a interface aparece, mas ROOT_URL gera links de clone com localhost ou a porta SSH não é encaminhada. Recriar o container raramente resolve um conflito entre URLs, estado e dependências.

Este guia usa um único critério concreto de conclusão: clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente. Cada decisão de configuração é avaliada com base nesse critério, e não apenas por um indicador verde do container.

Encontre todos os dados persistentes do Gitea

Liste o estado antes de criar o primeiro registro real: repositórios, objetos LFS, anexos, configuração e banco de dados. Monte /data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Confirme a montagem gravando dados inofensivos, substituindo o Gitea e lendo os dados novamente.

Snapshots são úteis para rollback rápido, mas é necessário ter um backup independente quando o host ou o volume desaparece. Restaure em um ambiente vazio usando a imagem fixada e verifique se os repositórios passam no fsck, se os objetos LFS podem ser baixados e se as issues, releases e permissões de usuário correspondem ao estado anterior ao backup. Use volumes persistentes e snapshots para manter esses dois mecanismos de recuperação distintos.

Crie um container do Gitea que possa ser substituído

O comando a seguir torna visível o limite do container sem fingir provisionar todos os serviços externos.

docker run -d \
  --name gitea \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__security__SECRET_KEY=replace-with-a-long-random-value \
  gitea/gitea:latest

Antes de abrir o ingress, inspecione o ambiente resolvido, as montagens e o listener. Adicione as configurações de conexão revisadas para Postgres ou MySQL em uma instalação mais movimentada e uma rota SSH, se necessário; use nomes privados para serviços privados. Uma inicialização bem-sucedida termina quando você consegue clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente — não quando docker ps exibe Up.

Separe o Gitea das dependências

A saúde do processo e a saúde do produto são coisas distintas no Gitea. A porta 3000 pode responder enquanto a transação voltada ao usuário ainda falha. O contrato de rede do Gitea é o Postgres ou MySQL para uma instalação mais movimentada e uma rota SSH, se necessário. Mantenha endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Gitea uma credencial de serviço com escopo limitado.

Use este exercício de readiness após mudanças relevantes de configuração: clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente. Mantenha verificações externas dispendiosas fora dos liveness probes para que uma indisponibilidade do provedor não cause um loop de reinicialização. O trabalho de capacidade deve acompanhar a quantidade de repositórios, o empacotamento de objetos Git, o armazenamento LFS, a latência do banco de dados e a carga do runner, em vez de solicitações comuns de página, que refletem melhor a pressão real sobre o Gitea.

TLS é fácil; URLs geradas, não

Exponha um único hostname HTTPS para o Gitea e mantenha a porta 3000 privada. Defina ROOT_URL e SSH_DOMAIN com os endereços que os usuários realmente usam para clonar. Isso impede que navegadores e clientes de API conheçam dois endereços concorrentes.

Em um cliente limpo, execute a transação conhecida como válida e inspecione a primeira solicitação que falhar. Use o guia de domínio personalizado quando houver problemas de DNS ou TLS. Trate “ROOT_URL gera links de clone com localhost ou a porta SSH não é encaminhada” como um diagnóstico separado da aplicação depois que a rota tiver sido comprovada.

Comprove o funcionamento do deployment do Gitea de ponta a ponta

Não use o tráfego do primeiro usuário como teste de aceitação do Gitea. Prepare um estado de exemplo inofensivo e execute a ação completa “clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente”. Registre a URL pública exata, o resultado, a referência da imagem e o intervalo de logs associado à execução.

Substitua o container e repita o processo sem recriar os dados. Em seguida, faça a recuperação em um host vazio; a condição de recuperação é que os repositórios passem no fsck, os objetos LFS possam ser baixados e as issues, releases e permissões de usuário correspondam ao estado anterior ao backup. Observe a quantidade de repositórios, o empacotamento de objetos Git, o armazenamento LFS, a latência do banco de dados e a carga do runner em todas as execuções e defina um alerta para a degradação da transação, e não para métricas de containers ociosos.

Uma verificação final deve falhar de propósito: negue temporariamente à identidade de teste o acesso ao Postgres ou MySQL em uma instalação mais movimentada e a uma rota SSH, se necessário. Verifique se a mensagem resultante do Gitea identifica o limite relevante, em vez de disparar a exclusão de dados ou uma reinicialização infinita. Restaure a condição válida e confirme que a mesma transação de exemplo é bem-sucedida. Mantenha este exercício curto na checklist de release.

Simule a mudança de Gitea mais arriscada

No Gitea, monitore uma transação em vez de um processo: clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente. Combine a latência e a taxa de erros da transação com a quantidade de repositórios, o empacotamento de objetos Git, o armazenamento LFS, a latência do banco de dados e a carga do runner, em vez de solicitações comuns de página, para que um alerta identifique o componente limitado.

O ensaio da atualização deve considerar que migrações de schema, hooks de repositório, packages e runners de terceiros exigem uma atualização do Gitea em etapas. Restaure, migre e execute a transação antes de substituir o ambiente de produção. Se ROOT_URL gerar links de clone com localhost ou a porta SSH não for encaminhada, não apague dados para fazer a inicialização parecer bem-sucedida; compare versão, variáveis, montagens e acessibilidade das dependências, nessa ordem.

Proteja a parte valiosa do Gitea

Após o primeiro login, revise o que um visitante anônimo, um usuário comum e um administrador podem fazer. O problema do Gitea a evitar é manter o instalador ou a primeira conta de administrador acessíveis por mais tempo do que o necessário. A política desejada é fechar o instalador após o bootstrap, restringir a administração do site e manter os tokens de registro de runners com vida curta.

Trate GITEA__security__SECRET_KEY de acordo com sua função no Gitea: mantenha valores sensíveis fora do Git, documente os efeitos da rotação e nunca substitua um exemplo público em produção. Mantenha contas de dependências separadas das contas humanas, negue o egress não utilizado quando for viável e limite o trabalho influenciado pela quantidade de repositórios, pelo empacotamento de objetos Git, pelo armazenamento LFS, pela latência do banco de dados e pela carga do runner, em vez de solicitações comuns de página.

O que o Dockup deve automatizar para o Gitea

Para o Gitea, o Dockup pode criar a rota e o certificado TLS, preservar as montagens, entregar secrets e disponibilizar o Postgres ou MySQL para uma instalação mais movimentada e uma rota SSH, se necessário, em uma rede privada, enquanto faz o deployment no Dockup ou em servidores conectados.

O gate de release continua sendo a transação concreta do Gitea: clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente. Verifique também a condição de restauração: os repositórios passam no fsck, os objetos LFS podem ser baixados e as issues, releases e permissões de usuário correspondem ao estado anterior ao backup. Essas duas verificações mostram se o deployment funciona e se pode ser recuperado.

Perguntas frequentes

O que o Gitea precisa para um deployment de produção?

Encaminhe o container do Gitea na porta 3000 por uma única origem HTTPS. O requisito de rede de suporte é o Postgres ou MySQL para uma instalação mais movimentada e uma rota SSH, se necessário. Não considere o Gitea pronto até conseguir clonar por HTTPS e SSH, fazer push de um commit e de um objeto LFS, abrir uma issue e executar um job em um Actions runner registrado separadamente.

Quais dados do Gitea devem fazer parte de um backup?

Torne /data persistente e inclua repositórios, objetos LFS, anexos, configuração e banco de dados no mesmo manifesto de recuperação. Uma restauração limpa do Gitea só é bem-sucedida quando os repositórios passam no fsck, os objetos LFS podem ser baixados e as issues, releases e permissões de usuário correspondem ao estado anterior ao backup.

O Gitea exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Gitea e mantenha a porta 3000 na rota interna. Aplique corretamente a configuração do Gitea: defina ROOT_URL e SSH_DOMAIN com os endereços que os usuários realmente usam para clonar. No Gitea, o HTTPS protege credenciais ou conteúdo de usuários durante o trânsito e mantém consistente o comportamento dos clientes sensível à origem.

Como uma atualização do Gitea deve ser testada?

Restaure o estado atual do Gitea em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Tenha atenção especial porque migrações de schema, hooks de repositório, packages e runners de terceiros exigem uma atualização do Gitea em etapas. Mantenha a imagem anterior do Gitea até entender os limites da migração de dados e do rollback.