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

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

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

# 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

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

# 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

   # 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

   # 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

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

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:

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

# 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

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

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

Referencias

• Forgejo Documentation
• Forgejo Actions
• Forgejo Runner