agent_platform_oci/specs/en/SPEC-017-Release-Management-and-CICD.md

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

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

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.