# SPEC-017 — Release Management and CI/CD

## Agent Platform OCI

Version: 1.0.0


---

## Reading guide

each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.

The document structure is:

1. Concept.
2. Problem addressed.
3. When to use.
4. When not to use.
5. Architecture.
6. Implementation.
7. Examples.
8. Common errors.
9. Acceptance criteria.

---


# 1. Concept

Release management Defines como changes entram on the platform, are testadas, empacotadas, publicadas, promovidas and auditadas.

CI/CD automatiza Validations and reduz Risk operacional.

# 2. Pipeline Standard

```mermaid
flowchart LR
    C[Commit] --> L[Lint]
    L --> TC[Type Check]
    TC --> UT[Unit Tests]
    UT --> IT[Integration Tests]
    IT --> CT[Contract Tests]
    CT --> SS[Security Scan]
    SS --> B[Build]
    B --> P[Publish]
    P --> DD[Deploy Dev]
    DD --> ST[Smoke Tests]
    ST --> CERT[Certification]
    CERT --> HML[Deploy HML]
    HML --> PROD[Deploy Prod]
```

# 3. Stages

| Stage | Função |
| --- | --- |
| validate | Validation inicial of structure. |
| lint | Estilo and erros simples. |
| type_check | Tipos and contracts Python. |
| unit_test | Tests unitários. |
| integration_test | Integrações locais. |
| contract_test | contracts JSON/YAML/API. |
| security_scan | Dependências, secrets and imagens. |
| build_package | Wheel/package. |
| build_image | Imagem Docker. |
| publish | Registry/artifacts. |
| deploy_dev | Ambiente dev. |
| smoke_test | Health and Calls básicas. |
| certification | Certification Suite. |
| deploy_hml | Homologação. |
| deploy_prod | Production. |


# 4. artifacts of release

- imagem Docker;
- pacote Python;
- release notes;
- matriz of compatibility;
- migration guide when necessário;
- evaluator report;
- certification report;
- SBOM when aplicável;
- evidência of scan;
- changelog.

# 5. Example of pipeline

```yaml
stages:
  - lint
  - test
  - contract
  - security
  - build
  - publish
  - deploy
  - certification
```

# 6. Gates

| Gate | when applies |
| --- | --- |
| Architecture Gate | changes estruturais, contracts, runtime, gateways. |
| Security Gate | Segredos, Identity, Data sensíveis, MCP External. |
| Quality Gate | Tests, evaluator, certification. |
| Operations Gate | Dashboards, Alerts, runbook, rollback. |


# 7. Estratégia of rollback

Rollback must restaurar:

- imagem previous;
- Configuration previous;
- Contract previous;
- prompt previous;
- dataset previous when necessário;
- migration of banco when aplicável.

# 8. Common errors

| Error | Impact | Correction |
| --- | --- | --- |
| Deploy without certification | Risk funcional. | Rodar certification no pipeline. |
| without release notes | without rastreabilidade. | Publicar release notes. |
| without contract tests | Quebra integration. | Adicionar Tests of Contract. |
| without rollback | Risk operacional. | Definir estratégia of rollback. |


# 9. Acceptance criteria

- [ ] Pipeline executa lint, type check and Tests.
- [ ] Contract tests executam.
- [ ] Security scan executa.
- [ ] Imagem Docker gerada.
- [ ] Artifacts publicados.
- [ ] Smoke tests executados.
- [ ] Certification executada.
- [ ] Release notes publicadas.
- [ ] Rollback definido.
- [ ] Evidências arquivadas.