Rodolpho Lopes 200cd6c2ce kb: KB-PLUGIN-031 runbook de workflow dev/deploy de plugins + commit dos registros 021-030 pendentes

- Novo runbook KB-PLUGIN-031: nascimento do plugin ate validacao E2E no
  GLPI dev (scaffold, Forgejo local, deploy CT100, console, bootstrap
  Kernel para testes CLI). Validado de ponta a ponta com o assetinherit.
- Registros KB-PLUGIN-021..030 existiam apenas no disco (drift) e foram
  incluidos no versionamento; index.json sincronizado via kb-fix.
- Ignora lixo AppleDouble/.DS_Store do macOS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-11 17:59:47 +00:00

6.9 KiB

Raw Blame History

title

domain

mcprotocol — Fluxo de release Dev → Prod (manual)

Contexto

O ecossistema Mindplace usa dois Forgejos: um de desenvolvimento (lab) e um de produção (Mindtek). O fluxo de release é híbrido: push automático para dev via git push normal, push para prod via script semi-automatizado.

A versão do plugin é a mesma entre dev e prod — não há suffixo -dev, -rc, etc. A diferença é qual Forgejo recebeu o push.

Topologia

┌─────────────────────────────┐
│   Workspace local (CT100)   │
│   /opt/projects/GLPI11/     │
│      docker/glpi/           │
│      marketplace/mcprotocol │
└──────────────┬──────────────┘
               │
               │  git push origin main
               ▼
┌─────────────────────────────────────────┐
│  Forgejo DEV (lab, CT101)               │
│  git@192.168.100.101:                   │
│       administrador/mcprotocol.git      │
│  Uso: desenvolvimento, homologação      │
└──────────────┬──────────────────────────┘
               │
               │  homologação OK ─►  bin/mindplace-release.sh
               ▼
┌─────────────────────────────────────────┐
│  Forgejo PROD (Mindtek)                 │
│  https://servicedesk.mindtek.com.br/git │
│       /rodolpho.lopes/mcprotocol        │
│  Uso: release oficial, marketplace      │
└──────────────┬──────────────────────────┘
               │
               │  Mindplace catálogo lê do prod
               ▼
┌─────────────────────────────────────────┐
│  Mindplace (catálogo)                   │
│  plugins.json no repo "mindplace"       │
│  + Banco Postgres /api/admin/sync       │
└─────────────────────────────────────────┘

Fluxo passo a passo

1. Desenvolvimento

Editar código no plugin (src/, setup.php, etc.)
Testar localmente contra https://glpi.lab.coretoai.com/

2. Push em Dev

cd /opt/projects/GLPI11/docker/glpi/marketplace/mcprotocol
git add <arquivos>
git commit -m "feat/fix/chore: ..."
git push origin main   # vai pro Forgejo lab (192.168.100.101)

3. Homologação

Testar end-to-end via curl ou cliente MCP apontando para o GLPI lab
Iterar até estável

4. Bump de versão (quando for liberar release)

// setup.php
define('PLUGIN_MCPROTOCOL_VERSION', 'X.Y.Z');  // semver

Commit + push para dev primeiro.

5. Push em Prod (manual, via script)

cd /opt/projects/MindPlace
./bin/mindplace-release.sh ./docker/glpi/plugins/mcprotocol
# Ou se o plugin estiver em outro caminho:
./bin/mindplace-release.sh /opt/projects/GLPI11/docker/glpi/marketplace/mcprotocol

O script executa 5 fases:

Cria/valida repo no Forgejo de prod (servicedesk.mindtek.com.br/git/rodolpho.lopes/mcprotocol)
git push do código pro Forgejo de prod
Gera ZIP do plugin (vide KB-PLUGIN-018 sobre wrapper conventions)
Cria release vX.Y.Z + upload do ZIP como release asset
Atualiza plugins.json no repo mindplace (catálogo central)

Pré-requisitos:

FORGEJO_TOKEN em /opt/projects/MindPlace/bin/.forgejo-token (gitignored)
Token com escopo write:repository, write:user no Forgejo de prod
Acesso ao repo mindplace (catálogo)

6. Detecção pelo Mindplace

Hoje: GET /api/admin/sync chama o endpoint do Mindplace, que faz upsert na tabela App (Prisma) para cada repo do Forgejo de prod.
Em prod: este fluxo funciona corretamente — o catálogo reflete os plugins.
Gaps conhecidos (vide diagnóstico em CT100, lab):
- Sync é pull manual, não tem trigger por webhook
- Schema App não tem campo version — não detecta release nova
- forgejoService.getLatestRelease() existe mas o endpoint /sync não o usa
- Não há sistema de notificação de update

Convenções

Item	Convenção
Versão	SemVer (`MAJOR.MINOR.PATCH`)
Dev e prod com versão idêntica	Sim — mesma versão em ambos os ambientes
Branch principal	`main` em ambos Forgejos
Mensagem de commit	Prefixos `feat:`, `fix:`, `chore:`, `docs:` (Conventional Commits)
Bump de versão	Commit isolado tipo `chore(release): bump X.Y.Z → X.Y.W`
Tag de release	Criada só no Forgejo de prod, pelo script (`vX.Y.Z`)

Quando usar dev vs prod

Situação	Forgejo
Desenvolvimento em andamento, testes da lab	Dev (192.168.100.101)
Validação com cliente piloto interno	Dev
Pronto pra ir pra marketplace (catálogo público)	Prod (servicedesk.mindtek.com.br)
Hotfix urgente em cliente	Pula homologação? Avaliar caso a caso

Recuperação

Reescrita de histórico no dev

Forçar push com --force-with-lease (preferível) ou --force (irreversível para colaboradores)
Sempre comunicar a equipe se há mais de 1 colaborador no repo

Rollback de release em prod

Reverter o commit problemático no repo do plugin
Bump de PATCH (ex: 1.1.1 → 1.1.2 com fix)
Re-rodar mindplace-release.sh
Não deletar release antiga — Mindplace pode ter clientes apontando para ela

Roadmap para automação da Fase 4 (futuro)

Gaps que valem ser fechados quando houver bandwidth:

Webhook Forgejo → Mindplace — disparar sync quando push acontece no prod
Schema App.version — capturar versão atual + permitir comparação
Notificação de update — e-mail/push pra clientes com licenças ativas quando há release nova
Cron de sync periódico — backup pra caso webhook falhe (ex: a cada 15min)

Estes gaps estão documentados também no diagnóstico do plugin (KB-PLUGIN-026, seção "Próximos passos do Mindplace").

Status atual

Fluxo 1-3 (dev): ✅ funcionando, automação simples via git push
Fluxo 5 (prod): ✅ funcionando em produção, validado com plugins anteriores
Fluxo 6 (Mindplace catalog): ✅ funcionando em produção, embora seja pull manual
Detecção automática de versão / notificação: ⏳ backlog

6.9 KiB Raw Blame History