docs: publish gitea host operations guide

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