# 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
       |
   git push origin main    (GitHub - backup)
   git push forgejo main   (Forgejo - CI/CD)
       |
   Forgejo (git.esdrasrenan.com.br)
       |
   Forgejo Actions (dispara automaticamente)
       |
   Forgejo Runner (VPS)
       |
   Docker Swarm deploy
```

**Fluxo:** Push para ambos os remotes. O push para `forgejo` dispara o CI/CD.

```bash
# Push para ambos (recomendado)
git push origin main && git push forgejo main

# Ou use o alias configurado
git push-all
```

## 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

O repositorio no Forgejo recebe pushes diretos (nao e mais um mirror).

### Uso diario

```bash
# Trabalhe normalmente
git add .
git commit -m "sua mensagem"

# Push para GitHub (backup) e Forgejo (CI/CD)
git push origin main && git push forgejo main

# Acompanhe o CI/CD em:
# https://git.esdrasrenan.com.br/esdras/sistema-de-chamados/actions
```

### Configurar alias (opcional)

```bash
# Adicionar alias para push em ambos
git config alias.push-all '!git push origin main && git push forgejo main'

# Usar:
git push-all
```

## 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, usando Bun)
3. **convex_deploy** - Deploy das functions Convex
4. ~~**desktop_release**~~ - Build do app desktop (comentado - sem runner Windows)

### 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. **runs-on:** Usar labels do self-hosted runner em vez de `ubuntu-latest`
   ```yaml
   # GitHub Actions (hosted runner)
   runs-on: ubuntu-latest

   # Forgejo Actions (self-hosted)
   runs-on: [ self-hosted, linux, vps ]
   ```

4. **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

# Se o runner mostrar erro "404 Not Found" apos reinicio do Forgejo:
systemctl restart forgejo-runner
```

### Workflow nao dispara apos push

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)
4. **Regenerar hooks do repositorio:**
   ```bash
   docker exec -u 1000:1000 $(docker ps -q --filter "name=forgejo_forgejo") \
     /usr/local/bin/gitea admin regenerate hooks --config /data/gitea/conf/app.ini
   ```

### Erro de LevelDB Lock (queue nao inicia)

Se o Forgejo mostrar erro `unable to lock level db at /data/gitea/queues/common`:

1. O stack.yml ja usa `FORGEJO__queue__TYPE=channel` para evitar esse problema
2. Se o erro persistir, limpe o diretorio de queues:
   ```bash
   docker exec $(docker ps -q --filter "name=forgejo_forgejo") \
     rm -rf /data/gitea/queues/*
   docker service update --force forgejo_forgejo
   ```

### 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)