Gitea: Guia Completo de Forge Git Auto-hospedado e Alternativa ao GitHub

TL;DR — Resumo Rápido

Implante o Gitea como forge Git auto-hospedado. Cobre Docker Compose, Gitea Actions, LDAP, OAuth2, registros de pacotes, mirroring e proxy reverso Caddy.

O Gitea é um forge Git leve e auto-hospedado escrito em Go que é distribuído como um único binário e funciona confortavelmente em hardware tão modesto quanto um Raspberry Pi. Se você já quis controle total sobre seu código-fonte, pipelines de CI/CD, rastreamento de issues e registros de pacotes sem pagar pelos preços do GitHub ou GitLab na nuvem — e sem o peso operacional de uma instância do GitLab CE — o Gitea é a resposta. Este guia cobre desde um deployment de produção com Docker Compose até Gitea Actions CI, SSO com OAuth2, registros de pacotes e mirroring de repositórios.

Pré-requisitos

• Docker e Docker Compose v2 instalados no host
• Um nome de domínio apontando para o servidor (para TLS com Caddy)
• Pelo menos 512 MB de RAM e 2 GB de disco (Gitea precisa de ~150 MB; reserve o restante para PostgreSQL e repositórios)
• Familiaridade básica com volumes Docker e sintaxe YAML
• Porta 3000 (ou 80/443 via proxy reverso) acessível da sua rede

Arquitetura do Gitea

O Gitea é uma aplicação Go compilada em um único binário sem dependências em tempo de execução. Inclui um servidor web, hooks do Git, um daemon SSH e workers em segundo plano. Opções de armazenamento:

Backend	Ideal para	Notas
SQLite	Usuário único / pequenas equipes	Zero config; não adequado para alta concorrência
PostgreSQL	Equipes e produção	Recomendado; melhor desempenho
MySQL / MariaDB	Infraestrutura MySQL existente	Suportado; PostgreSQL preferido

Os dados de repositórios são armazenados como repos Git bare no disco em $GITEA_WORK_DIR/repositories. Objetos LFS vão para $GITEA_WORK_DIR/lfs. Anexos, avatares e pacotes usam $GITEA_WORK_DIR/data.

Gitea vs Forgejo vs Alternativas

Forge	Linguagem	RAM (idle)	Actions CI	Registro de pacotes	Licença
Gitea	Go	~120 MB	Sim (act_runner)	Sim (11 tipos)	MIT
Forgejo	Go	~120 MB	Sim (act_runner)	Sim	MIT
GitLab CE	Ruby/Go	~2–4 GB	Sim (nativo)	Sim	MIT
Gogs	Go	~50 MB	Não	Não	MIT
OneDev	Java	~500 MB	Sim	Limitado	MIT
Sourcehut	Python/Go	~100 MB	Sim (builds.sr.ht)	Não	AGPL

O Forgejo é compatível em API com o Gitea e os runners são intercambiáveis. A migração entre os dois é simples. O GitLab CE é muito mais completo em funcionalidades, mas requer entre 10 e 20 vezes mais recursos.

---

Passo 1: Implantar com Docker Compose e PostgreSQL

Crie um diretório de projeto e um docker-compose.yml:

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=changeme
    volumes:
      - gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: gitea-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=gitea
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  gitea-data:
  postgres-data:

docker compose up -d

Abra http://seu-servidor:3000 em um navegador. O instalador web preenche previamente as configurações do banco de dados a partir das variáveis de ambiente. Configure apenas a URL base, o nome de usuário administrador, o e-mail do administrador e a senha do administrador, depois clique em Instalar. O Gitea inicializa o esquema do banco de dados e redireciona para o painel em segundos.

---

Passo 2: Configurar app.ini

Após a execução do instalador, app.ini fica no volume Docker em gitea/conf/app.ini. Edite-o para reforçar a configuração:

[server]
DOMAIN           = git.exemplo.com
ROOT_URL         = https://git.exemplo.com/
HTTP_PORT        = 3000
SSH_DOMAIN       = git.exemplo.com
SSH_PORT         = 22
SSH_LISTEN_PORT  = 22
DISABLE_SSH      = false
LFS_START_SERVER = true

[repository]
DEFAULT_BRANCH          = main
ENABLE_PUSH_CREATE_USER = false
DEFAULT_PRIVATE         = private

[security]
INSTALL_LOCK              = true
SECRET_KEY                = <gere-com-openssl-rand-hex-32>
INTERNAL_TOKEN            = <gere-com-gitea-generate-secret>
MIN_PASSWORD_LENGTH       = 12
PASSWORD_COMPLEXITY       = lower,upper,digit,spec

[service]
DISABLE_REGISTRATION              = false
REQUIRE_SIGNIN_VIEW               = false
REGISTER_EMAIL_CONFIRM            = true
ENABLE_NOTIFY_MAIL                = true

[mailer]
ENABLED   = true
SMTP_ADDR = smtp.exemplo.com
SMTP_PORT = 587
FROM      = "Gitea <gitea@exemplo.com>"
USER      = gitea@exemplo.com
PASSWD    = `sua-senha-smtp`

Reinicie para aplicar:

docker compose restart gitea

---

Passo 3: Gerenciamento de Repositórios

Git LFS

LFS é habilitado com LFS_START_SERVER = true em [server]. Os usuários configuram seu cliente local uma vez:

git lfs install
git lfs track "*.psd" "*.zip" "*.tar.gz"

Espelhamento de Repositórios

Os mirrors pull permitem ao Gitea clonar e sincronizar periodicamente do GitHub, GitLab ou qualquer remoto Git. Na interface web: Novo Repositório → Migrar. Selecione a fonte e marque Este repositório será um mirror com o intervalo de sincronização desejado.

Os mirrors push enviam cada commit para um remoto automaticamente. Configure em Configurações do repositório → Configurações de mirror → Push Mirrors.

Branches Protegidos e Estratégias de Merge

Em Configurações do repositório → Branches → Adicionar regra de proteção de branch:

• Exigir revisões de pull request — defina aprovações mínimas
• Exigir verificações de status — bloqueie o merge se o fluxo de trabalho de Actions falhar
• Restringir push — lista branca de equipes ou usuários
• Estratégias de merge — habilite/desabilite merge commit, squash e rebase por repositório

---

Passo 4: Gitea Actions CI

O Gitea Actions é o sistema de CI integrado que usa a mesma sintaxe YAML do GitHub Actions.

Registrar um act_runner

Baixe o último binário act_runner de https://gitea.com/gitea/act_runner/releases. No painel de administração vá para Administração do site → Actions → Runners → Criar novo token de runner.

# Registrar o runner
act_runner register \
  --instance https://git.exemplo.com \
  --token <token-runner> \
  --name meu-runner \
  --labels ubuntu-latest:docker://node:20-bullseye

# Iniciar como serviço
act_runner daemon

Exemplo de Fluxo de Trabalho

# .gitea/workflows/build.yml
name: Compilar e Testar

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm test

  docker:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Construir imagem Docker
        run: docker build -t minhaapp:${{ gitea.sha }} .
      - name: Publicar no registro do Gitea
        run: |
          docker login git.exemplo.com -u ${{ secrets.REGISTRY_USER }} -p ${{ secrets.REGISTRY_TOKEN }}
          docker push git.exemplo.com/minhaorg/minhaapp:${{ gitea.sha }}

---

Passo 5: Gerenciamento de Usuários e Autenticação

Contas Locais e 2FA

2FA via TOTP está disponível em Configurações do usuário → Segurança → Autenticação de dois fatores.

LDAP / Active Directory

Administração do site → Identidade e acesso → Fontes de autenticação → LDAP (via BindDN):

• Host: ldap.exemplo.com
• Porta: 389 (ou 636 para LDAPS)
• Bind DN: cn=gitea,ou=contas-servico,dc=exemplo,dc=com
• Base de busca de usuários: ou=usuarios,dc=exemplo,dc=com
• Filtro de usuário: (&(objectClass=person)(sAMAccountName=%s))

Provedores OAuth2

Adicione login com GitHub, GitLab ou Google em Fontes de autenticação → OAuth2:

Provedor	Origem do Client ID	Escopo
GitHub	github.com/settings/developers	read:user,user:email
GitLab	gitlab.com/-/profile/applications	read_user
Google	console.cloud.google.com	openid email profile

---

Passo 6: Proxy Reverso Caddy com TLS

Adicione isso ao seu Caddyfile:

git.exemplo.com {
    reverse_proxy gitea:3000

    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Frame-Options "SAMEORIGIN"
        X-Content-Type-Options "nosniff"
    }
}

O Caddy obtém certificados Let’s Encrypt automaticamente na primeira requisição ao domínio.

---

Organizações, Equipes e Permissões

Papel	Repositórios	Painel admin	Criar repos
Proprietário	Todos na org	Sim	Sim
Admin (equipe)	Repos da equipe	Não	Escopo da equipe
Escrita (equipe)	Repos da equipe	Não	Não
Leitura (equipe)	Repos da equipe	Não	Não

Registro de Pacotes do Gitea

Habilite o registro de pacotes em app.ini:

[packages]
ENABLED = true

Tipos de pacotes suportados: npm, PyPI, Maven, NuGet, Docker/OCI, Composer, Cargo, Conan, Helm, RubyGems e APT Alpine/Debian.

Backup e Restauração

# Dentro do container
docker exec -u git gitea gitea dump -c /data/gitea/conf/app.ini \
  -t /tmp --type tar.gz

# Copiar o arquivo para fora
docker cp gitea:/tmp/gitea-dump-*.tar.gz ./backups/

Migração do GitHub, GitLab ou Gogs

Administração do site → Migrações suporta importação completa preservando issues, pull requests, labels, milestones, releases e páginas wiki. A migração do Gogs para o Gitea é transparente — o Gitea lê o banco de dados do Gogs diretamente.

Problemas Comuns e Casos Especiais

Conflito de porta SSH — Se a porta 22 já é usada pelo daemon SSH do host, mapeie o SSH do Gitea para uma porta diferente (ex.: 222:22) e atualize SSH_PORT em app.ini.

Docker-in-Docker com act_runner — Para fluxos de trabalho que constroem imagens Docker, o runner precisa de acesso ao socket do Docker. Monte /var/run/docker.sock no container do runner.

Crescimento do armazenamento LFS — Objetos LFS não são coletados automaticamente. Agende gitea admin repo-lfs-prune periodicamente.

Solução de Problemas

Problema	Solução
Interface web retorna 502	Verifique docker logs gitea; confirme variáveis de ambiente de conexão ao BD
Clone via SSH falha	Confirme que SSH_PORT corresponde ao mapeamento de porta do host
Fluxo de Actions na fila para sempre	Verifique se act_runner está em execução e registrado; confira as labels
Push de pacote com erro 401	Gere um token com escopo package; use-o como senha do registro
Mirror não sincroniza	Verifique se a URL do mirror é acessível do container

Resumo

• Gitea funciona com ~120 MB de RAM como binário Go único — muito mais leve que o GitLab CE
• Docker Compose com PostgreSQL é o deployment de produção recomendado
• app.ini controla cada aspecto: segurança, mailer, LFS, pacotes e SSH
• Gitea Actions usa a sintaxe YAML do GitHub Actions; act_runner executa jobs em containers Docker
• LDAP, OAuth2 (GitHub/GitLab/Google) e TOTP 2FA são integrados
• Os registros de pacotes suportam npm, PyPI, Maven, NuGet, Docker/OCI e mais
• O mirroring de repositórios (push e pull) mantém repositórios externos sincronizados automaticamente

Artigos Relacionados

• ArgoCD GitOps para Deployments no Kubernetes
• Primeiros Passos com GitHub Actions CI/CD
• Guia de Configuração de Pipelines CI/CD com GitLab
• Vaultwarden Gerenciador de Senhas Auto-hospedado
• Docker Compose para Deployments em Produção