Como usar o Forgejo ou Gitea como alternativa self-hosted ao GitHub

1. Introdução ao Forgejo e Gitea: Por que migrar do GitHub?

A dependência de plataformas centralizadas como o GitHub levanta questões crescentes sobre privacidade, controle de dados e custos operacionais. Para organizações que precisam de soberania sobre seus repositórios, o movimento de auto-hospedagem (self-hosting) oferece uma solução robusta. Duas ferramentas se destacam nesse cenário: Forgejo e Gitea.

Ambas são forges de código aberto, leves e compatíveis com Git, projetadas para rodar em infraestrutura própria. A principal diferença está na governança: o Gitea é mantido pela Gitea Ltd., enquanto o Forgejo surgiu como um fork comunitário após preocupações com a governança corporativa do projeto original. Ambos compartilham a mesma base de código até certo ponto, mas divergem em filosofia e frequência de releases.

Casos de uso ideais incluem:
- Equipes pequenas que desejam evitar custos de planos pagos do GitHub
- Organizações com requisitos de compliance (LGPD, GDPR, dados sensíveis)
- Projetos pessoais onde o desenvolvedor quer controle total sobre o código

2. Instalação e configuração inicial de um servidor self-hosted

Os pré-requisitos são modestos: um servidor Linux (Ubuntu 22.04 ou Debian 12), Docker e Docker Compose, e um banco de dados SQLite (para testes) ou PostgreSQL (para produção). O exemplo abaixo usa Docker Compose para subir o Gitea em minutos.

Crie um arquivo docker-compose.yml:

version: "3"

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=sqlite3
      - GITEA__server__DOMAIN=git.exemplo.com
      - GITEA__server__HTTP_PORT=3000
      - GITEA__server__ROOT_URL=https://git.exemplo.com
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "22:22"
    restart: always

Para subir o serviço:

docker-compose up -d

Acesse http://seu-servidor:3000 para concluir a configuração via interface web. Para HTTPS, configure um proxy reverso com Nginx e certbot:

server {
    listen 443 ssl;
    server_name git.exemplo.com;

    ssl_certificate /etc/letsencrypt/live/git.exemplo.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.exemplo.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Para Forgejo, substitua a imagem por codeberg.org/forgejo/forgejo:latest e ajuste as variáveis de ambiente conforme a documentação oficial.

3. Migrando repositórios do GitHub para o seu servidor

Existem duas abordagens principais para migrar repositórios.

Método manual com mirror:

git clone --mirror https://github.com/usuario/repositorio.git
cd repositorio.git
git remote set-url origin https://git.exemplo.com/usuario/repositorio.git
git push --mirror origin

Método automático via interface web:
No painel do Gitea/Forgejo, vá em "Migração" > "Importar repositório". Informe a URL do GitHub e um token de acesso pessoal (se o repositório for privado). A ferramenta importa automaticamente issues, pull requests e wikis, embora com algumas limitações:
- Labels personalizadas podem não ser transferidas completamente
- Hooks e webhooks precisam ser reconfigurados manualmente
- Releases e anexos de issues podem ser perdidos em migrações complexas

4. Gerenciamento de equipes e permissões

Ambas as plataformas oferecem controle granular de acesso. Crie organizações e times com permissões específicas:

# Exemplo de estrutura de times
Organização: "minha-empresa"
  - Time "devs" (permissão de escrita em repositórios de desenvolvimento)
  - Time "admins" (permissão de administração em todos os repositórios)
  - Time "readers" (permissão de leitura em repositórios internos)

Para integração com autenticação externa, configure LDAP ou OAuth no arquivo app.ini:

[oauth2]
ENABLED = true
PROVIDER = github
CLIENT_ID = seu_client_id
CLIENT_SECRET = seu_client_secret

5. Automação com Actions (Forgejo) / CI/CD embutido

Tanto Gitea quanto Forgejo possuem Actions nativas, compatíveis com a sintaxe YAML do GitHub Actions. Para usar, é necessário configurar um runner.

Exemplo de workflow .gitea/workflows/build.yml:

name: Build e Testes
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Instalar dependências
        run: npm install
      - name: Rodar testes
        run: npm test
      - name: Build
        run: npm run build

Para registrar um runner local:

# Baixar o binário do runner
wget -O gitea-runner https://codeberg.org/forgejo/forgejo/releases/download/v1.21/forgejo-runner-linux-amd64
chmod +x gitea-runner

# Registrar no servidor
./gitea-runner register --instance https://git.exemplo.com --token SEU_TOKEN

6. Extensões e integrações essenciais

Webhooks para notificações:
Configure webhooks no repositório para enviar eventos para Slack, Discord ou sistemas de monitoramento:

URL do webhook: https://hooks.slack.com/services/T000000/B000000/XXXXXXXX
Eventos: push, pull request, issues

LFS (Large File Storage):
Para binários grandes, ative o LFS no arquivo app.ini:

[lfs]
ENABLED = true
PATH = /data/git/lfs

Backup com gitea dump:
O comando nativo gera um arquivo com todo o banco de dados e repositórios:

docker exec -it gitea gitea dump --file /data/backup/backup-$(date +%Y%m%d).zip

7. Manutenção, segurança e boas práticas

Atualizações seguras:
Sempre faça backup antes de atualizar. Verifique as notas de release para breaking changes:

# Backup completo
docker exec -it gitea gitea dump --file /tmp/pre-upgrade.zip

# Atualizar imagem
docker-compose pull
docker-compose up -d

Firewall e proteção:
Configure fail2ban para bloquear tentativas de login:

[gitea]
enabled = true
filter = gitea
logpath = /var/log/gitea/gitea.log
maxretry = 5
bantime = 3600

Monitoramento básico:
Verifique logs e uso de disco regularmente:

# Logs em tempo real
docker logs -f gitea

# Espaço em disco
df -h /data/gitea

8. Considerações finais e próximos passos

A escolha entre Forgejo e Gitea depende da sua filosofia e necessidades:
- Forgejo: ideal para quem prefere governança comunitária total e releases mais frequentes
- Gitea: melhor para quem quer suporte corporativo e estabilidade comprovada

Ambos são excelentes alternativas ao GitHub, mas apresentam limitações: ecossistema menor de integrações, ausência de Codespaces nativo e menos templates de CI/CD prontos. Para equipes que precisam de funcionalidades avançadas como GitHub Copilot ou Actions complexas, a migração pode exigir adaptações.

Recursos da comunidade incluem documentação oficial, fóruns no Discourse e canais Matrix. Comece com um repositório de teste, explore as Actions e configure backups automáticos. A auto-hospedagem não é apenas sobre economia — é sobre liberdade e controle do seu fluxo de desenvolvimento.

Referências