sistema-de-chamados/docs/FORGEJO-CI-CD.md

# Forgejo CI/CD - Documentacao

Este documento descreve a configuracao do Forgejo como alternativa ao GitHub Actions para CI/CD self-hosted.

## Por que Forgejo?

A partir de marco de 2026, o GitHub passara a cobrar $0.002 por minuto de execucao em self-hosted runners. O Forgejo Actions oferece a mesma experiencia visual e funcionalidade sem custo adicional.

## Arquitetura

```
Claude Code / VS Code
       |
   Git local
       |
   GitHub (repo principal) <---> Forgejo (mirror/CI)
                                    |
                             Forgejo Actions
                                    |
                             Forgejo Runner (VPS)
                                    |
                             Docker Swarm deploy
```

## URLs e Credenciais

| Servico | URL | Usuario |
|---------|-----|---------|
| Forgejo UI | https://git.esdrasrenan.com.br | esdras |
| Forgejo SSH | git@git.esdrasrenan.com.br:2222 | - |
| Actions | https://git.esdrasrenan.com.br/esdras/sistema-de-chamados/actions | - |

**Senha inicial:** `ForgejoAdmin2025!` (altere apos primeiro acesso)

## Estrutura de Arquivos

```
projeto/
├── .forgejo/
│   └── workflows/
│       ├── ci-cd-web-desktop.yml    # Deploy principal (VPS + Convex)
│       └── quality-checks.yml       # Lint, test, build
├── .github/
│   └── workflows/                   # Workflows originais do GitHub
│       └── ...
└── forgejo/
    ├── stack.yml                    # Stack Docker do Forgejo
    └── setup-runner.sh              # Script de setup do runner
```

## Configuracao na VPS

### Forgejo Server

Rodando como servico Docker Swarm:

```bash
# Localização do stack
/srv/forgejo/stack.yml

# Comandos uteis
docker service ls --filter "name=forgejo"
docker service logs forgejo_forgejo --tail 100
docker stack deploy -c /srv/forgejo/stack.yml forgejo
```

### Forgejo Runner

Rodando como servico systemd:

```bash
# Localização
/srv/forgejo-runner/

# Arquivos
/srv/forgejo-runner/forgejo-runner    # Binario
/srv/forgejo-runner/config.yaml       # Configuracao
/srv/forgejo-runner/.runner           # Registro

# Comandos uteis
systemctl status forgejo-runner
systemctl restart forgejo-runner
journalctl -u forgejo-runner -f

# Labels do runner
- ubuntu-latest:docker://node:20-bookworm
- self-hosted:host
- linux:host
- vps:host
```

## Fluxo de Trabalho

### Opcao 1: Push para ambos (recomendado)

Configure o git para fazer push automatico para GitHub e Forgejo:

```bash
# Adicionar Forgejo como remote
git remote add forgejo https://git.esdrasrenan.com.br/esdras/sistema-de-chamados.git

# OU configurar push para ambos no origin
git remote set-url --add --push origin https://git.esdrasrenan.com.br/esdras/sistema-de-chamados.git
git remote set-url --add --push origin https://github.com/esdrasrenan/sistema-de-chamados.git
```

### Opcao 2: Mirror automatico

Configure o Forgejo para sincronizar automaticamente com o GitHub (requer token do GitHub para repos privados).

## Workflows Disponiveis

### ci-cd-web-desktop.yml

Triggers:
- Push na branch `main`
- Tags `v*.*.*`
- workflow_dispatch (manual)

Jobs:
1. **changes** - Detecta arquivos alterados
2. **deploy** - Deploy na VPS (Next.js + Docker Swarm)
3. **convex_deploy** - Deploy das functions Convex
4. **desktop_release** - Build do app desktop (tags `v*`)

### quality-checks.yml

Triggers:
- Push na branch `main`
- Pull requests para `main`

Jobs:
1. **lint-test-build** - Lint, testes e build

## Diferenca do GitHub Actions

Os workflows do Forgejo sao quase identicos aos do GitHub Actions. Principais diferencas:

1. **Localizacao:** `.forgejo/workflows/` em vez de `.github/workflows/`
2. **Actions URL:** Usar `https://github.com/` prefixo nas actions
   ```yaml
   # GitHub Actions
   uses: actions/checkout@v4

   # Forgejo Actions
   uses: https://github.com/actions/checkout@v4
   ```

3. **Secrets:** Configurar em Settings > Actions > Secrets no Forgejo

## Manutencao

### Atualizar Forgejo

```bash
ssh root@154.12.253.40
cd /srv/forgejo
# Editar stack.yml para nova versao da imagem
docker stack deploy -c stack.yml forgejo
```

### Atualizar Runner

```bash
ssh root@154.12.253.40
cd /srv/forgejo-runner
systemctl stop forgejo-runner

# Baixar nova versao
RUNNER_VERSION="6.2.2"  # ajustar versao
curl -sL -o forgejo-runner "https://code.forgejo.org/forgejo/runner/releases/download/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-amd64"
chmod +x forgejo-runner

systemctl start forgejo-runner
```

### Re-registrar Runner

Se o runner perder a conexao:

```bash
ssh root@154.12.253.40
cd /srv/forgejo-runner

# Gerar novo token no Forgejo
docker exec -u 1000:1000 $(docker ps -q --filter "name=forgejo_forgejo") \
  /usr/local/bin/gitea --config /data/gitea/conf/app.ini actions generate-runner-token

# Re-registrar
systemctl stop forgejo-runner
rm .runner
./forgejo-runner register \
  --instance https://git.esdrasrenan.com.br \
  --token "NOVO_TOKEN" \
  --name "vps-runner" \
  --labels "ubuntu-latest:docker://node:20-bookworm,self-hosted:host,linux:host,vps:host" \
  --no-interactive
systemctl start forgejo-runner
```

### Backup

```bash
# Backup do volume do Forgejo
docker run --rm -v forgejo_forgejo_data:/data -v /backup:/backup alpine \
  tar czf /backup/forgejo-backup-$(date +%Y%m%d).tar.gz /data
```

## Troubleshooting

### Runner nao aparece online

```bash
# Verificar status
systemctl status forgejo-runner
journalctl -u forgejo-runner --no-pager -n 50

# Verificar conectividade
curl -s https://git.esdrasrenan.com.br/api/healthz
```

### Workflow nao dispara

1. Verificar se o arquivo esta em `.forgejo/workflows/`
2. Verificar se Actions esta habilitado no repositorio (Settings > Actions)
3. Verificar se o runner esta online (Settings > Actions > Runners)

### Erro de permissao no deploy

O runner precisa de acesso ao Docker:

```bash
# Verificar grupo docker
groups runner
# Adicionar se necessario
usermod -aG docker runner
systemctl restart forgejo-runner
```

## Referencias

- [Forgejo Documentation](https://forgejo.org/docs/)
- [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/)
- [Forgejo Runner](https://code.forgejo.org/forgejo/runner)