docs: publish gitea host operations guide

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

@@ -0,0 +1,38 @@
+# Gitea Actions em Host Mode
+
+Esta documentação descreve a operação real do ambiente de Gitea Actions em host mode já validado em produção.
+
+## O que esta solução faz
+
+- executa workflows do Gitea Actions no servidor real, sem Docker nos jobs
+- roda `git fetch`, `checkout`, `reset`, `clean` e o comando de deploy direto nas pastas reais
+- roda `git add`, `commit` e `push` direto nas pastas reais quando a operação é de commit local
+- suporta deploy de projetos Cloudflare e Vercel sem trocar a arquitetura já operacional
+
+## Workflows disponíveis
+
+- `host-deploy`: sincroniza a pasta real e executa o comando de deploy do projeto
+- `host-local-push`: commita e envia alterações locais da pasta real
+- `host-smoke`: valida runner, path, git, node, npm e npx sem fazer deploy
+- `host-ops`: agregador manual para `pull_deploy` ou `commit_push`
+
+## Como a operação funciona
+
+1. O workflow é disparado manualmente no repositório do projeto.
+2. O runner host mode consome o job na máquina real.
+3. O script entra no path real do projeto no servidor.
+4. O script sincroniza o Git ou faz commit local, conforme a operação.
+5. O comando de deploy roda na pasta real do projeto.
+
+## Ressalva importante sobre `runs-on`
+
+- o runner está registrado em host mode com label `linux_amd64:host`
+- nesta instância Gitea `1.25.3`, o agendamento operacional dos workflows funciona com `runs-on: linux_amd64`
+- não force `runs-on: linux_amd64:host` nos workflows ativos, porque isso já demonstrou deixar job em fila sem consumo
+
+## Documentos relacionados
+
+- [Runner](runner.md)
+- [Workflows](workflows.md)
+- [Projetos](projects.md)
+- [Troubleshooting](troubleshooting.md)

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

@@ -0,0 +1,31 @@
+# Projetos Atendidos
+
+## gptstj_workers
+
+- path real: `/root/__gpt-codex/gptstj_workers`
+- branch de deploy: `main`
+- remote Git: `origin -> https://git.ami.app.br/admin/gptstj_workers.git`
+- comando de deploy: `./scripts/actions/deploy_all.sh`
+- observações:
+  - deploy via `npx wrangler deploy`
+  - rotas operando em `ami.app.br`
+
+## tools
+
+- path real: `/root/__gpt-codex/tools`
+- branch de deploy: `main`
+- remote Git: `origin -> https://git.ami.app.br/admin/tools.git`
+- comando de deploy: `./scripts/actions/deploy_all.sh`
+- observações:
+  - deploy via `npx wrangler deploy`
+  - workers atuais publicados em `ami-app.workers.dev`
+
+## vercel
+
+- path real: `/root/__gpt-codex/vercel`
+- branch de deploy: `main`
+- remote Git: `origin -> https://git.ami.app.br/admin/vercel.git`
+- comando de deploy: `./scripts/actions/deploy_all.sh`
+- observações:
+  - deploy via Vercel CLI
+  - cada app precisa de `.vercel/project.json` válido no path real do projeto

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

@@ -0,0 +1,44 @@
+# Runner
+
+## Instalação real
+
+- binário: `/usr/local/bin/act_runner`
+- arquivo de registro: `/var/lib/act_runner/.runner`
+- configuração: `/etc/act_runner/config.yaml`
+- ambiente do serviço: `/etc/act_runner/env`
+
+## Usuário e serviço
+
+- usuário efetivo do runner: `root`
+- serviço systemd: `act_runner.service`
+- comportamento esperado: `enabled` e `active`
+
+## Label registrada
+
+- label registrada no runner: `linux_amd64:host`
+
+## Caveat do `runs-on`
+
+- registro do runner: `linux_amd64:host`
+- valor operacional dos workflows: `linux_amd64`
+- motivo: nesta instância Gitea `1.25.3`, o consumo real dos jobs já validados funciona com `runs-on: linux_amd64`
+
+## Como validar que o runner está online
+
+```bash
+systemctl status act_runner --no-pager -l
+cat /var/lib/act_runner/.runner
+```
+
+## Como reiniciar o serviço
+
+```bash
+systemctl restart act_runner.service
+```
+
+## Como ver logs do serviço
+
+```bash
+journalctl -u act_runner -n 200 --no-pager
+journalctl -u act_runner -f
+```

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

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

@@ -0,0 +1,98 @@
+# Workflows
+
+## Lista de workflows
+
+- `host-deploy.yml`
+- `host-local-push.yml`
+- `host-smoke.yml`
+- `host-ops.yml`
+
+## O que cada workflow faz
+
+### host-deploy
+
+- valida o path e o repositório Git
+- roda `git fetch`, `checkout`, `reset --hard FETCH_HEAD` e `git clean -fd`
+- executa `DEPLOY_CMD` na pasta real do projeto
+
+### host-local-push
+
+- valida o path e o repositório Git
+- roda `git add -A`
+- cria commit local com a mensagem informada
+- faz `git push` para o remote configurado
+
+### host-smoke
+
+- não faz deploy
+- imprime `pwd`
+- valida `DEPLOY_PATH`, `DEPLOY_BRANCH`, `DEPLOY_REMOTE`, `DEPLOY_CMD`
+- valida `git status`, `node`, `npm` e `npx`
+
+### host-ops
+
+Workflow agregador para operação manual humana.
+
+Inputs:
+
+- `operation`: `pull_deploy` ou `commit_push`
+- `commit_message`: opcional
+
+Comportamento:
+
+- `pull_deploy` chama `./scripts/actions/host_deploy.sh`
+- `commit_push` chama `./scripts/actions/host_push.sh`
+
+## Variables usadas
+
+Compartilhadas:
+
+- `DEPLOY_PATH`
+- `DEPLOY_BRANCH`
+- `DEPLOY_REMOTE`
+- `DEPLOY_CMD`
+
+## Secrets usados
+
+Obrigatórios para push:
+
+- `HOST_GITEA_TOKEN`
+- `HOST_GIT_AUTHOR_NAME`
+- `HOST_GIT_AUTHOR_EMAIL`
+
+Opcionais para deploy:
+
+- `HOST_CLOUDFLARE_API_TOKEN`
+- `HOST_VERCEL_TOKEN`
+
+## Fallback host/Gitea para secrets
+
+Ordem de precedência:
+
+1. se o workflow receber o secret opcional do Gitea, o valor do workflow é usado
+2. se o secret opcional não existir, o runner continua usando o ambiente do host
+3. no caso do Cloudflare, também é aceito login OAuth já configurado no usuário do runner
+4. no caso do Vercel, também é aceito login já configurado no CLI do usuário do runner
+
+Isso preserva o modo atual funcional sem tornar secrets opcionais obrigatórios.
+
+## Como disparar pull + deploy
+
+- pelo workflow `host-deploy`
+- ou pelo workflow `host-ops` com `operation=pull_deploy`
+
+## Como disparar commit + push local
+
+- pelo workflow `host-local-push`
+- ou pelo workflow `host-ops` com `operation=commit_push`
+
+## Smoke test manual
+
+Use `host-smoke` para diagnóstico rápido antes de um deploy.
+
+Verificações esperadas:
+
+- branch atual correta
+- `git status` responde
+- `node`, `npm` e `npx` respondem
+- variables do workflow estão presentes