[328] Gitea: Self-Hosted Leve para Times Menores

O GitLab self-hosted é poderoso — e pesado. Uma instalação completa consume vários gigabytes de RAM mesmo em repouso, exige PostgreSQL, Redis, MinIO ou S3, e requer atenção operacional constante com atualizações mensais. Para o problema que resolve — uma plataforma DevOps completa para centenas ou milhares de usuários — esse custo é justificado.

Mas há um conjunto de casos de uso onde esse custo não é justificado: times pequenos (2 a 30 pessoas), projetos internos que não precisam de CI/CD sofisticado, laboratórios de desenvolvimento, ambientes air-gapped com recursos limitados, ou simplesmente a necessidade de um mirror privado de repositórios com autenticação básica.

Para esses casos, o Gitea é a resposta. É um servidor Git self-hosted escrito em Go, distribuído como um único binário, que roda com menos de 100MB de RAM e pode usar SQLite como banco de dados. Toda a interface, API compatível com GitHub e funcionalidades básicas em um arquivo executável.

Instalação: Um Binário, Uma Máquina

A instalação mais simples do Gitea não requer Docker, Kubernetes, banco de dados externo ou qualquer dependência além do próprio binário:

# Instalar o Gitea em um servidor Linux

# Criar usuário dedicado (boa prática de segurança)
sudo adduser \
  --system \
  --shell /bin/bash \
  --gecos 'Git Version Control' \
  --group \
  --disabled-password \
  --home /home/git \
  git

# Criar diretórios necessá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/
sudo mkdir /etc/gitea
sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea

# Baixar o binário (verificar versão atual em gitea.io)
wget -O /usr/local/bin/gitea \
  https://dl.gitea.com/gitea/1.22.0/gitea-1.22.0-linux-amd64
chmod +x /usr/local/bin/gitea

# Criar serviço systemd para inicialização automática
sudo tee /etc/systemd/system/gitea.service > /dev/null <<EOF
[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target
Wants=postgresql.service

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable gitea
sudo systemctl start gitea

# Acessar http://servidor:3000 para completar a instalação via interface

Instalação com Docker Compose

Para ambientes onde o Docker já está disponível, o Docker Compose oferece mais portabilidade e facilidade de backup:

# docker-compose.yml
version: '3.8'

services:
  gitea:
    image: gitea/gitea:1.22.0
    container_name: gitea
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=postgres:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${DB_PASSWORD}
      - GITEA__server__DOMAIN=git.empresa.com
      - GITEA__server__SSH_DOMAIN=git.empresa.com
      - GITEA__server__ROOT_URL=https://git.empresa.com/
      - GITEA__server__HTTP_PORT=3000
      - GITEA__mailer__ENABLED=true
      - GITEA__mailer__SMTP_ADDR=smtp.empresa.com
      - GITEA__mailer__SMTP_PORT=587
      - GITEA__mailer__FROM=gitea@empresa.com
      - GITEA__mailer__USER=gitea@empresa.com
      - GITEA__mailer__PASSWD=${SMTP_PASSWORD}
      # Desabilitar registro público — apenas admin cria usuários
      - GITEA__service__DISABLE_REGISTRATION=true
      - GITEA__service__REQUIRE_SIGNIN_VIEW=true
    ports:
      - "3000:3000"
      - "222:22"  # SSH em porta alternativa (host 222 → container 22)
    volumes:
      - gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=gitea
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  gitea-data:
  postgres-data:

Gitea Actions: CI/CD Compatível com GitHub Actions

A partir da versão 1.19, o Gitea implementou o Gitea Actions — um sistema de CI/CD que usa a mesma sintaxe do GitHub Actions. Workflows .github/workflows/*.yml do GitHub podem ser executados no Gitea com pouca ou nenhuma modificação, usando o act_runner (o agente de execução).

Essa compatibilidade é um diferencial significativo: times que migram do GitHub para Gitea por razões de custo ou soberania de dados não precisam reescrever seus workflows. A grande maioria das actions do GitHub Marketplace também funciona no Gitea, desde que não dependam de serviços específicos do GitHub.

# .github/workflows/ci.yml — funciona tanto no GitHub quanto no Gitea

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  testes:
    runs-on: ubuntu-latest  # O act_runner provisiona o ambiente

    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpass
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4

      - name: Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Instalar dependências
        run: npm ci

      - name: Testes
        run: npm test
        env:
          DATABASE_URL: postgresql://testuser:testpass@localhost:5432/testdb

      - name: Build
        run: npm run build

Para habilitar o Gitea Actions, é necessário instalar o act_runner — o agente que executa os workflows:

# Instalar o act_runner na mesma máquina ou em outra dedicada

wget -O act_runner \
  https://dl.gitea.com/act_runner/0.2.10/act_runner-0.2.10-linux-amd64
chmod +x act_runner

# Registrar o runner no Gitea
# O token de registro está em: Admin → Site Administration → Runners
./act_runner register \
  --instance https://git.empresa.com \
  --token TOKEN-DE-REGISTRO \
  --name "runner-principal" \
  --labels "ubuntu-latest:docker://node:20" \
  --no-interactive

# Iniciar o runner como serviço systemd
sudo tee /etc/systemd/system/act_runner.service > /dev/null <<EOF
[Unit]
Description=Gitea Act Runner
After=network.target

[Service]
ExecStart=/usr/local/bin/act_runner daemon
WorkingDirectory=/var/lib/act_runner
Restart=always
User=git

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now act_runner

Mirroring: Gitea como Espelho Privado

Um caso de uso valioso do Gitea é como espelho privado de repositórios públicos. Times que dependem de repositórios open-source externos podem criar mirrors internos para garantir disponibilidade mesmo se o GitHub estiver fora do ar, ou para conformidade com políticas que proíbem downloads diretos da internet durante builds:

# Via API REST do Gitea (compatível com a API do GitHub)
curl -X POST https://git.empresa.com/api/v1/repos/migrate \
  -H "Content-Type: application/json" \
  -H "Authorization: token $GITEA_TOKEN" \
  -d '{
    "clone_addr": "https://github.com/expressjs/express",
    "repo_name": "express",
    "mirror": true,
    "mirror_interval": "8h",
    "private": true,
    "description": "Mirror do Express.js — sincronizado a cada 8h"
  }'

O Gitea sincroniza automaticamente o mirror no intervalo configurado. Builds internos podem referenciar git.empresa.com/mirrors/express em vez de github.com/expressjs/express.

Limitações do Gitea

A leveza do Gitea tem um custo: funcionalidades enterprise que o GitLab oferece nativamente precisam ser compostas com outras ferramentas ou simplesmente não estão disponíveis. Não há SAST integrado, não há Container Registry nativo (embora haja suporte experimental), não há gestão avançada de projetos, não há pages para documentação estática.

Para times pequenos com necessidades simples — repositório Git privado, CI/CD básico com Gitea Actions, mirroring e controle de acesso por organização — o Gitea resolve o problema com uma fração da complexidade operacional do GitLab. Para times que crescem e precisam de mais, a migração de Gitea para GitLab é bem definida: ambos suportam a API REST do GitLab em graus diferentes, e o GitLab tem um importer nativo para Gitea.

Os artigos anteriores (GitLab CI/CD: A Alternativa Enterprise ao GitHub Actions, GitLab Self-Hosted: Soberania Total sobre Código e Pipelines, Bitbucket e o Ecossistema Atlassian) cobriram o panorama completo das principais alternativas ao GitHub para hospedagem de código e CI/CD. O GitLab CI/CD (E5) como plataforma SaaS com funcionalidades enterprise integradas de segurança. O GitLab self-hosted (E6) para organizações que precisam de soberania total sobre código e pipelines. O Bitbucket (E7) para o contexto específico do ecossistema Atlassian com Jira no centro. E o Gitea (E8) para times pequenos que precisam de simplicidade e leveza.

O denominador comum entre todas essas plataformas é que o conhecimento central — Git, pipelines YAML, containers, Kubernetes, observabilidade — é transferível. A sintaxe muda. Os princípios permanecem.

Referências para Aprofundamento

• Gitea — Documentação Oficial
• Gitea Actions
• act_runner — Gitea Act Runner
• Gitea API v1
• Comparação de Plataformas Git Self-Hosted

Exercícios

Exercício 1

O docker-compose.yml do artigo não monta nenhum arquivo app.ini, mas mesmo assim configura banco, domínio, SMTP e registro de usuários. Como? Descreva a regra que transforma GITEA__server__ROOT_URL na configuração correspondente.

[server]
ROOT_URL = https://git.empresa.com/

Exercício 2

No compose, o mapeamento de portas é "3000:3000" e "222:22". Por que a porta SSH do host é 222 e não 22? E qual é a consequência disso na URL de clone que o desenvolvedor vai usar?

# Não funciona — a forma abreviada não tem onde colocar a porta
git clone git@git.empresa.com:org/repo.git

# Funciona — URL ssh:// completa
git clone ssh://git@git.empresa.com:222/org/repo.git

Exercício 3

O act_runner register passa --labels "ubuntu-latest:docker://node:20". O workflow do artigo declara runs-on: ubuntu-latest. O que acontece se o runner for registrado sem esse label, e o workflow continuar igual?

Exercício 4

A chamada à API de migração usa "mirror": true com "mirror_interval": "8h". Um desenvolvedor abre o repositório express espelhado no Gitea, corrige um typo no README e tenta dar push. O que acontece — e por quê?

Exercício 5

Na instalação por binário, os diretórios recebem tratamentos diferentes: /var/lib/gitea fica git:git com 750, e /etc/gitea fica root:git com 770. Por que o dono do diretório de configuração é o root, se quem roda o serviço é o usuário git?

sudo chmod 750 /etc/gitea
sudo chmod 640 /etc/gitea/app.ini