knowledge-base/records/plugin-dev/KB-PLUGIN-027-mcprotocol-dev-prod-release-flow.md

---
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