---
id: release-management
agent: devops
title: Criar release versionada
inputs: [versão alvo, diff desde a última tag]
outputs: [changelog, tag, GitHub release, caminho de rollback]
elicit: true
modes: [interactive]
---

# Criar release versionada

**Objetivo:** publicar uma release versionada — changelog gerado, tag semântica e GitHub release —
após confirmação humana, com o caminho de reversão claro. Release é exclusiva do @devops.

**Pré-condições:**
- A branch base (`main`/`master`) está verde: gate de qualidade passou e está sincronizada com o
  remoto. Se há trabalho não auditado, **pare** e rode o `pre-push-quality-gate`.
- A versão alvo respeita SemVer e foi confirmada via `*version-check` (ver `version-management`). Sem
  bump confirmado, **pare**.

## Passos

1. **Detecte o contexto do repositório** — remoto, branch base e a última tag (`git describe --tags`).
   Nunca assuma repo fixo.
2. **Reúna o diff desde a última tag** (`git log {ultima-tag}..HEAD`) — a fonte do changelog. Tudo
   rastreia a commits/stories reais; sem invenção de itens de release.
3. **Gere o changelog** agrupando por tipo (feat, fix, breaking) a partir dos conventional commits.
4. **Confirme o bump semântico.** MAJOR se há breaking change no diff; MINOR para feature compatível;
   PATCH para fix. Se a versão alvo não bate com o diff, sinalize a divergência.
5. **Revele a release proposta.** Mostre versão, changelog e a tag a criar.
6. **[ELICITAÇÃO] Peça o "ok" explícito.** Release é irreversível na prática — exige confirmação humana.
7. **Crie a tag** (`git tag -a v{versão}`) e a **GitHub release** (`gh release create`) com o changelog
   como corpo. Empurre a tag para o remoto.
8. **Reporte e deixe o rollback claro.** Devolvo a URL da release e o caminho de reversão (deletar tag
   local/remota e a release pelo `gh` caso publicada por engano).

## Critério de pronto (DoD)

- [ ] Última tag detectada e diff coletado dinamicamente
- [ ] Changelog gerado a partir dos commits reais (sem invenção)
- [ ] Bump semântico coerente com o diff e confirmado
- [ ] Confirmação humana obtida antes de tagear/publicar
- [ ] Tag criada, release publicada e URL reportada com caminho de rollback

## Falha / recuperação

- **Bump diverge do diff** (ex.: PATCH com breaking change) → paro e re-confirmo a versão; SemVer é lei.
- **Branch base não está verde** → não faço release; volto ao gate.
- **Usuário não confirma** → não crio tag nem release.
- **Tag já existe** → não sobrescrevo; reporto o conflito e proponho a próxima versão.
- **Release publicada por engano** → executo o rollback documentado (deletar tag remota + release),
  com novo "ok" do usuário.