172 lines
6.9 KiB
Markdown
172 lines
6.9 KiB
Markdown
---
|
|
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 <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)
|
|
```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
|