Hospedando seu próprio servidor Git com Gitea

1. Introdução ao Gitea e auto-hospedagem Git

Gitea é uma plataforma de auto-hospedagem Git leve e eficiente, escrita em Go. Originalmente um fork do Gogs, o Gitea rapidamente se tornou uma das soluções mais populares para quem deseja controle total sobre seus repositórios Git. Sua natureza leve o torna ideal para servidores com recursos limitados, consumindo muito menos memória e CPU que alternativas como GitLab.

As vantagens da auto-hospedagem são significativas: controle absoluto sobre seus dados, privacidade garantida, sem limites impostos por terceiros, e a possibilidade de personalizar cada aspecto do servidor. Enquanto GitHub e GitLab oferecem planos gratuitos limitados, o Gitea permite repositórios ilimitados sem custos recorrentes.

Comparado ao GitLab, que pode exigir 4GB de RAM para funcionar adequadamente, o Gitea roda confortavelmente em servidores com 512MB de RAM. Já os serviços externos como GitHub, GitLab.com e Bitbucket impõem limites de armazenamento, colaboradores e funcionalidades em seus planos gratuitos.

Pré-requisitos para instalação:
- Servidor Linux (Ubuntu 22.04 LTS ou Debian 11 recomendados)
- Acesso root ou sudo
- Domínio configurado (opcional, mas recomendado para HTTPS)
- Portas 22 (SSH) e 80/443 (HTTP) disponíveis

2. Instalação do Gitea via binário ou Docker

Instalação manual com binário pré-compilado

A instalação manual oferece controle total sobre cada etapa:

# Criar usuário dedicado
sudo adduser --system --shell /bin/bash --gecos 'Git Version Control' \
  --group --disabled-password --home /home/git git

# Download do binário
sudo wget -O /usr/local/bin/gitea \
  https://dl.gitea.io/gitea/1.21.0/gitea-1.21.0-linux-amd64
sudo chmod +x /usr/local/bin/gitea

# Criar estrutura de diretórios
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R git:git /var/lib/gitea
sudo chmod -R 750 /var/lib/gitea

# Configurar service systemd
sudo wget -O /etc/systemd/system/gitea.service \
  https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/systemd/gitea.service
sudo systemctl enable gitea
sudo systemctl start gitea

Instalação via Docker Compose

Para ambientes conteinerizados, o Docker Compose simplifica o gerenciamento:

# docker-compose.yml
version: "3"

services:
  gitea:
    image: gitea/gitea:1.21
    container_name: gitea
    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=gitea123
    restart: always
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db

  db:
    image: postgres:15
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea123
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

Após iniciar os containers com docker-compose up -d, acesse http://seu-servidor:3000 para a configuração inicial.

Configuração inicial no navegador

No primeiro acesso, o Gitea exibe um formulário de configuração. Preencha:
- Título do site: "Meu Git Server"
- Domínio: git.seudominio.com
- Porta SSH: 22 (ou 2222 no Docker)
- Banco de dados: PostgreSQL (recomendado) ou SQLite (para testes)
- Caminho dos repositórios: /home/git/gitea-repositories

Verificação pós-instalação

Teste o acesso SSH:

ssh -T git@git.seudominio.com
# Resposta esperada: Hi there, You've successfully authenticated...

Clone um repositório de teste:

git clone git@git.seudominio.com:usuario/repositorio.git

3. Configuração de autenticação e segurança

Autenticação local

No painel administrativo, configure políticas de senha:

# Em Admin > Configurações > Autenticação
- Comprimento mínimo: 8 caracteres
- Exigir caracteres especiais: Sim
- Bloqueio após 5 tentativas: Sim
- Expiração de senha: 90 dias

Integração com OAuth2

Para habilitar login via GitHub:

# Em Configurações do Site > Provedores de Autenticação
1. Clique em "Adicionar Provedor"
2. Selecione "GitHub OAuth2"
3. Client ID e Client Secret obtidos em: 
   https://github.com/settings/developers
4. URL de callback: https://git.seudominio.com/user/oauth2/GitHub/callback

HTTPS com Let's Encrypt via Caddy

Caddy simplifica a obtenção de certificados SSL:

# Caddyfile
git.seudominio.com {
    reverse_proxy localhost:3000
}

Com apenas essas linhas, o Caddy obtém e renova automaticamente certificados Let's Encrypt.

Configuração de chaves SSH

Usuários devem adicionar chaves SSH:

# No servidor local do usuário
ssh-keygen -t ed25519 -C "seu@email.com"
cat ~/.ssh/id_ed25519.pub
# Copie a chave e adicione em: 
# Configurações > Chaves SSH > Adicionar Chave

# Teste a conexão
ssh -T git@git.seudominio.com
# Deve retornar: Hi there, You've successfully authenticated...

4. Gerenciamento de repositórios e equipes

Criação de repositórios

# Pelo terminal, após criar no Gitea:
git init meu-projeto
cd meu-projeto
echo "# Meu Projeto" > README.md
git add README.md
git commit -m "Primeiro commit"
git remote add origin git@git.seudominio.com:usuario/meu-projeto.git
git push -u origin main

Organizações e times

Crie organizações para departamentos ou projetos:

1. No Gitea, vá em "Explorar" > "Organizações"
2. Crie "minha-empresa"
3. Adicione times:
   - Desenvolvedores (acesso de escrita)
   - Revisores (acesso de leitura + permissão para merge)
   - Admins (acesso total)

Proteção de branches

# Em Configurações do Repositório > Branches > Regras de Proteção
- Branch: main
- Habilitar:
  - [x] Proteger este branch
  - [x] Exigir push via pull request
  - [x] Exigir aprovações: 2
  - [x] Bloquear merge se status check falhar
  - [x] Excluir branch após merge

Hooks do Git

Webhooks para CI/CD:

# Em Configurações > Webhooks
URL: https://jenkins.seudominio.com/gitea-webhook/post
Tipo de conteúdo: application/json
Eventos:
  - [x] Push
  - [x] Pull Request
  - [x] Issues

5. Migração de repositórios existentes para o Gitea

Migração via mirror (interface web)

1. No Gitea, clique em "+" > "Nova Migração"
2. URL do repositório: https://github.com/usuario/repositorio.git
3. Tipo: GitHub
4. Marque:
   - [x] Migrar issues
   - [x] Migrar pull requests
   - [x] Migrar labels
   - [x] Migrar milestones
   - [x] Migrar wiki
5. Clique em "Migrar Repositório"

Migração manual com mirror

Para controle total do processo:

# Clone mirror do repositório original
git clone --mirror https://github.com/usuario/repositorio.git
cd repositorio.git

# Push mirror para o Gitea
git remote add novo git@git.seudominio.com:usuario/repositorio.git
git push --mirror novo

# Verificar preservação
git branch -a  # Deve mostrar todas as branches
git tag -l     # Deve mostrar todas as tags

Atualização de remotos locais

Cada desenvolvedor deve atualizar seus clones locais:

git remote set-url origin git@git.seudominio.com:usuario/repositorio.git
git remote -v  # Verificar novo remote

6. Manutenção e backup do servidor Git

Backup automatizado com cron

#!/bin/bash
# /usr/local/bin/backup-gitea.sh

# Backup do banco de dados PostgreSQL
pg_dump -U gitea gitea > /backup/gitea-db-$(date +%Y%m%d).sql

# Backup dos repositórios
tar -czf /backup/gitea-repos-$(date +%Y%m%d).tar.gz /var/lib/gitea/data/gitea-repositories

# Backup das configurações
cp /var/lib/gitea/custom/conf/app.ini /backup/

# Manter backups dos últimos 30 dias
find /backup -name "*.sql" -mtime +30 -delete
find /backup -name "*.tar.gz" -mtime +30 -delete

Agende no crontab:

0 3 * * * /usr/local/bin/backup-gitea.sh

Atualização do Gitea

# Para instalação manual
sudo systemctl stop gitea
sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.old
sudo wget -O /usr/local/bin/gitea https://dl.gitea.io/gitea/1.22.0/gitea-1.22.0-linux-amd64
sudo chmod +x /usr/local/bin/gitea
sudo systemctl start gitea

# Verificar atualização
sudo -u git /usr/local/bin/gitea --version

Verificação de integridade

# Verificar todos os repositórios
find /var/lib/gitea/data/gitea-repositories -name "*.git" -type d \
  -exec sh -c 'cd {}; git fsck --full' \;

# Verificar logs
tail -f /var/lib/gitea/log/gitea.log

7. Integração com ferramentas Git e fluxos avançados

Configuração de Git LFS

# No servidor Gitea, ativar LFS
# Em app.ini:
[server]
LFS_START_SERVER = true
LFS_JWT_SECRET = sua-chave-secreta-aqui

# No cliente local
git lfs install
git lfs track "*.psd" "*.zip" "*.tar.gz"
git add .gitattributes
git commit -m "Configurar LFS para arquivos grandes"
git push origin main

Gitea Actions (CI/CD nativo)

Configure runners para pipelines:

# .gitea/workflows/ci.yml
name: CI Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: |
          npm install
          npm test
      - name: Build
        run: npm run build

Hooks para notificações

Webhook para Slack:

# Em Configurações > Webhooks
URL: https://hooks.slack.com/services/T00/B00/xxxx
Tipo: Slack
Eventos:
  - Push
  - Pull Request (aberto/fechado)
  - Issues (abertas/fechadas)

Trabalho com submodules

# Adicionar submodule
git submodule add git@git.seudominio.com:libs/utils.git lib/utils
git submodule update --init --recursive

# Clonar com submodules
git clone --recurse-submodules git@git.seudominio.com:projeto/main.git

O Gitea oferece uma plataforma Git completa, leve e controlável. Com estas configurações, você tem um servidor Git profissional, seguro e pronto para produção, mantendo total controle sobre seus dados e fluxos de trabalho.

Referências