145 lines
3.2 KiB
Markdown
145 lines
3.2 KiB
Markdown
# 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.
|