docs: publish gitea host operations guide

docs/public/gitea-actions-host/troubleshooting.md

@@ -0,0 +1,112 @@
+# Troubleshooting
+
+## Runner online mas job não consome
+
+Verifique:
+
+```bash
+systemctl status act_runner --no-pager -l
+cat /var/lib/act_runner/.runner
+journalctl -u act_runner -n 200 --no-pager
+```
+
+## Problema com `runs-on`
+
+Sintoma:
+
+- runner online
+- workflow em fila
+- job não inicia
+
+Ação:
+
+- mantenha `runs-on: linux_amd64`
+- não troque os workflows ativos para `linux_amd64:host`
+
+## Path inexistente
+
+Mensagem esperada:
+
+- `Path does not exist: <path>`
+
+Verifique se `DEPLOY_PATH` aponta para uma pasta real do servidor.
+
+## Pasta não é repositório Git
+
+Mensagem esperada:
+
+- `Path is not a Git repository: <path>`
+
+## Branch inexistente
+
+Sintoma:
+
+- falha em `git fetch`, `checkout` ou `reset`
+
+Verifique:
+
+- valor de `DEPLOY_BRANCH`
+- existência da branch no remote configurado
+
+## Falha de atualização Git
+
+O fluxo operacional usa:
+
+- `git fetch`
+- `git checkout`
+- `git reset --hard FETCH_HEAD`
+- `git clean -fd`
+
+Verifique:
+
+- `DEPLOY_REMOTE`
+- token do Gitea
+- conectividade com `git.ami.app.br`
+
+## Falha de git push
+
+Verifique:
+
+- `HOST_GITEA_TOKEN`
+- `HOST_GIT_AUTHOR_NAME`
+- `HOST_GIT_AUTHOR_EMAIL`
+- se há mudanças staged pelo `git add -A`
+
+## Falha de npx deploy
+
+Cloudflare:
+
+- `HOST_CLOUDFLARE_API_TOKEN` opcional
+- fallback em `/etc/act_runner/env`
+- fallback adicional em login do Wrangler
+
+Vercel:
+
+- `HOST_VERCEL_TOKEN` opcional
+- fallback em sessão ativa do Vercel CLI
+
+## Falha por variável ausente
+
+Mensagem esperada:
+
+- `Missing required env: DEPLOY_*`
+
+## Falha por secret ausente
+
+Regras:
+
+- `HOST_GITEA_TOKEN` é obrigatório para deploy e push
+- `HOST_GIT_AUTHOR_*` é obrigatório para push
+- Cloudflare e Vercel são opcionais quando o host já tem credencial válida
+
+## Onde olhar logs
+
+Serviço do runner:
+
+```bash
+journalctl -u act_runner -n 200 --no-pager
+```
+
+Logs dos jobs:
+
+- `/var/lib/gitea/data/actions_log/...`