--- id: KB-PLUGIN-027 title: mcprotocol — Fluxo de release Dev → Prod (manual) domain: plugin-dev tags: - mcp - release - workflow - forgejo - mindplace status: active severity: medium created_at: 2026-05-26 updated_at: 2026-05-26 applies_to: - glpi-11 - mcprotocol-plugin - mindplace-marketplace related_records: - KB-PLUGIN-013 - KB-PLUGIN-018 - KB-PLUGIN-026 --- # 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 ```bash cd /home/glpi/glpi_dev/marketplace/mcprotocol git add 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) ```php // setup.php define('PLUGIN_MCPROTOCOL_VERSION', 'X.Y.Z'); // semver ``` Commit + push para dev primeiro. ### 5. Push em Prod (manual, via script) ```bash cd /opt/projects/MindPlace ./bin/mindplace-release.sh /home/glpi/glpi_dev/plugins/mcprotocol # Ou se o plugin estiver em outro caminho: ./bin/mindplace-release.sh /home/glpi/glpi_dev/marketplace/mcprotocol ``` O script executa 5 fases: 1. Cria/valida repo no Forgejo de prod (`servicedesk.mindtek.com.br/git/rodolpho.lopes/mcprotocol`) 2. `git push` do código pro Forgejo de prod 3. Gera ZIP do plugin (vide KB-PLUGIN-018 sobre wrapper conventions) 4. Cria release `vX.Y.Z` + upload do ZIP como release asset 5. 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 1. Reverter o commit problemático no repo do plugin 2. Bump de PATCH (ex: 1.1.1 → 1.1.2 com fix) 3. Re-rodar `mindplace-release.sh` 4. **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: 1. **Webhook Forgejo → Mindplace** — disparar sync quando push acontece no prod 2. **Schema `App.version`** — capturar versão atual + permitir comparação 3. **Notificação de update** — e-mail/push pra clientes com licenças ativas quando há release nova 4. **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