Pular para conteúdo

Forgejo e CI

O Forgejo é a forja Git da X-Adm: repositórios, issues, pull requests e CI (Forgejo Actions, sintaxe compatível com GitHub Actions).

Fluxo de trabalho

  • master (ou main): código estável e implantável.
  • Branches de trabalho: feature/nome-curto, fix/issue-123.
  • Mudança nasce numa issue → branch → commits → pull request → revisão → merge. Doc da mudança vai no mesmo PR (ver constituição).

Quem não usa Git edita arquivos Markdown direto pela interface web do Forgejo (botão de editar no arquivo → commit na branch ou PR automático).

Deploy automático via webhook

Deploy é responsabilidade do Coolify, não do Forgejo Actions. Cada push na branch configurada rebuilda e redeploya o app no Coolify, por webhook de repo:

  1. No Coolify: copiar a URL de webhook do recurso.
  2. No Forgejo: Settings do repo → Webhooks → Add Webhook → colar a URL, content type application/json, evento Push.

O Forgejo Actions cuida de build/publicação de docs (no Garage) e dos gates (qualidade, release) — nunca do deploy. (O site de docs já disparou o deploy por um passo curl no Actions; foi removido — duplicava o webhook de repo e quebrava sem a secret.)

Secrets no CI

  • Nunca commitar tokens, senhas de banco ou chaves — usar Settings → Actions → Secrets do repositório.
  • Secrets da plataforma vivem na organização xadm (todo repo da org herda, nada a criar por repo): DOCS_S3_* (publicação de docs). O aviso de falha não usa secret — é webhook nativo da org (abaixo).
  • Testcontainers no CI — o runner injeta DOCKER_HOST (topologia dind isolado). O act_runner da org roda um dind privilegiado e cria os jobs aninhados nele → montar o /var/run/docker.sock do host não funciona (o runner ignora: "not a valid volume"), o Testcontainers não acha Docker e todo @Testcontainers falha no CI (passando local) — o gate §6 "No CI (código)" fica vermelho crônico. Correção 2026-07-04 (o docker.sock/valid_volumes que documentei antes não vale nessa topologia): fix org-wide, mantendo o isolamento — injetar no config.yaml do act_runner (não no template) o env dos jobs: DOCKER_HOST=tcp://172.17.0.1:2375 (o gateway do dind — o nome dind da rede externa não resolve dentro do dind), TESTCONTAINERS_HOST_OVERRIDE=172.17.0.1, TESTCONTAINERS_RYUK_DISABLED=true. Assim o templates/ci.yml fica agnóstico (sem docker.sock, sem IP de topologia). Descoberto por probe (docker exec dind-* docker run --rm alpine wget http://172.17.0.1:2375/version).
  • Publicar Release no Forgejo (app que distribui artefato — release.yml opt-in): criar a Release via API precisa de escrita no repositório, e o GITHUB_TOKEN automático do Actions costuma ser só Actions (dá 403). Caminhos: (1) declarar permissions:\n contents: write no job (eleva o auto-token, se o instance permitir); (2) se restringir mesmo assim, criar um token dedicado — Forgejo → Settings → Applications → Generate New Token, escopo write:repository — e cadastrá-lo como secret da org RELEASE_TOKEN (o release.yml usa RELEASE_TOKEN se existir, senão o GITHUB_TOKEN). Detalhe em versionamento.

Aviso de falha no Telegram

Quando um Action falha, chega uma mensagem num chat do Telegram (repo, workflow, ref e link da run). Sem aviso, workflow quebrado fica dias sem ninguém ver. Isso é um webhook nativo da organização (Forgejo ≥ 12; instância em 15) — nada no YAML dos workflows, config única na org.

Configuração (uma vez, na organização)

  1. Criar o bot: no Telegram, falar com @BotFather → /newbot → guardar o token (123456:ABC-...).
  2. Descobrir o chat: criar o grupo/canal que receberá os avisos, adicionar o bot, mandar uma mensagem qualquer e abrir https://api.telegram.org/bot<TOKEN>/getUpdates — o chat.id aparece no JSON (grupo costuma ser negativo, ex. -100123456789).
  3. Criar o webhook na org xadm: Settings → Webhooks → Add Webhook → Telegram; preencher Bot Token e Chat ID; em Trigger On → Custom Events marcar Action Failure (e Recover, se quiser o aviso de recuperação); Active ligado. Webhook de organização cobre todos os repos — nada por app.

O Forgejo monta a mensagem e a URL da run sozinho. Testado no 15 com falha real (Action Failed in xadm/<repo> <branch>).

Token e chat ficam na config do webhook, não como secrets de Actions. Os antigos TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID da org ficaram órfãos com a migração ao webhook nativo (jun/2026) — podem ser removidos.

Checklist de PR

  • [ ] Testes passam (./gradlew test, flutter test, conforme a stack)
  • [ ] Mudou contrato/fluxo público → doc atualizada no mesmo PR
  • [ ] Frontmatter válido nos .md novos/alterados
  • [ ] Artefatos gerados (HTML de doc, relatórios) não commitados