Skip to content

Commit 3feaf84

Browse files
danielaEscdanielaEsc
committed
docs: actualizar propuesta de arquitectura de releases para reflejar implementacion actual
1 parent 82e92d8 commit 3feaf84

File tree

1 file changed

+98
-173
lines changed

1 file changed

+98
-173
lines changed

‎docs/research/epayco-release-agentes.md‎

Lines changed: 98 additions & 173 deletions
Original file line numberDiff line numberDiff line change
@@ -2,209 +2,134 @@
22

33
### 1. Contexto y objetivo
44

5-
**Problema a resolver**
6-
- **Automatizar releases** en múltiples proyectos/servicios (por ejemplo, servicios clave de ePayco).
7-
- **Mantener trazabilidad completa**: qué versión se libera, en qué entorno, cuándo, con qué commits y con qué aprobaciones.
8-
- **Reducir trabajo manual** en generación de changelogs, notas de release y registro de auditoría.
9-
10-
**Suposiciones actuales (para esta propuesta)**
11-
- **Repositorios**: GitHub (monorepos y/o varios repos por servicio).
12-
- **CI/CD**: GitHub Actions como plataforma principal.
13-
- **Versionado**: GitHub Action `release-please` como mecanismo estándar para generar ramas `release/vX.Y.Z`, PRs de release y tags.
14-
- **Skill local**: carpeta `release/` con `.releaserc.yml`, `CHANGELOG.md` y `skill.md` usada para orquestar parte del flujo de release con Copilot/agents.
15-
- **Auditoría**: workflow `.github/workflows/release-audit.yml` que hoy registra en `release/audit-log.jsonl` los eventos de creación de una rama `release/v*`.
16-
17-
**Objetivo de la investigación**
18-
Diseñar una arquitectura de **agentes + skills** integrados con GitHub Actions y `release-please` que:
19-
- Soporte **releases coordinados de múltiples proyectos**.
20-
- Aproveche el **número de release automático** que genera `release-please` (tag/versión como “fuente de verdad”).
21-
- Registre una **traza auditable consolidada** (JSONL / lago de datos) desde creación del release hasta despliegue por entorno.
22-
23-
### 2. Alcance
24-
25-
- **Proyectos cubiertos**: servicios backend y frontends que ya usan (o puedan usar) `release-please`.
26-
- **Entornos**: mínimo `dev`, `staging`, `prod` (extensible).
27-
- **Fases cubiertas**:
28-
- Generación de release (rama `release/v*`, PR, tag).
29-
- Despliegue por entorno, con aprobación humana cuando aplique.
30-
- Registro de auditoría por evento (creación, despliegue, rollback).
5+
**Problema a resolver**
316

32-
---
33-
34-
### 3. Opciones evaluadas
35-
36-
#### 3.1 Plataformas de CI/CD y orquestación
7+
- **Automatizar releases** en múltiples proyectos/servicios (por ejemplo, servicios clave de ePayco).
8+
- **Mantener trazabilidad completa**: qué versión se libera, en qué entorno, cuándo, con qué commits y con qué aprobaciones.
9+
- **Reducir trabajo manual** en generación de changelogs y registro de auditoría.
3710

38-
| Opción | Ventajas | Desventajas |
39-
| :------------------------------------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------- |
40-
| **GitHub Actions + release-please** | Integración nativa con repos, automatización basada en Conventional Commits, buen soporte multi‑repo. | Dependencia de GitHub, algunos patrones avanzados requieren workflows adicionales. |
41-
| **GitLab CI/CD + bots personalizados** | Pipelines declarativos potentes, control total sobre scripts y bots. | Requiere mantenimiento propio e infraestructura adicional. |
42-
| **Jenkins + pipelines compartidos** | Muy flexible y extensible, plugins para casi todo. | Mayor costo de operación y menor integración nativa con PRs de GitHub. |
43-
| **ArgoCD / Argo Workflows (GitOps)** | Control declarativo de despliegues en Kubernetes, excelente historial de cambios. | Curva de aprendizaje más alta, enfocado a Kubernetes. |
44-
| **GitHub Enterprise + Actions Advanced** | Auditoría reforzada, logs centralizados, controles de seguridad corporativos. | Opción de pago, no resuelve por sí misma la capa de agentes. |
11+
**Arquitectura actual (implementada en este repo)**
4512

46-
#### 3.2 Agentes/skills y frameworks
13+
| Componente | Responsabilidad |
14+
| ---------------------------------- | ----------------------------------------------------------------- |
15+
| **GitHub Action `release-please`** | Versionado semántico, creación de rama/PR de release y tag final |
16+
| **Skill local (`release/`)** | Documentación: genera/actualiza `release/CHANGELOG.md` en español |
17+
| **Workflow `release-audit.yml`** | Evento de auditoría JSONL al crear una rama `release/v*` |
4718

48-
- **GitHub Actions + LLMs vía API / Copilot**
49-
- Workflows en YAML que invocan APIs de agentes/LLMs para:
50-
- Validar convenciones.
51-
- Enriquecer changelogs y notas de release.
52-
- Completar y normalizar registros de auditoría.
19+
**Suposiciones actuales**
5320

54-
- **Microsoft Semantic Kernel (skills & planners)**
55-
- Skills para encapsular acciones como “leer changelog”, “generar resumen para stakeholders”, “registrar evento de auditoría”.
56-
- Planners para orquestar decisiones multi‑paso (por ejemplo, decidir qué pipeline de deploy lanzar en cada repo).
21+
- **Repositorios**: GitHub (monorepos y/o varios repos por servicio).
22+
- **CI/CD**: GitHub Actions como plataforma principal.
23+
- **Versionado**: GitHub Action `release-please` como mecanismo estándar, usando Conventional Commits para calcular la versión semántica.
24+
- **Skill local**: carpeta `release/` con `release-please-config.json`, `CHANGELOG.md`, `skill.md` y `README.md`, usada para documentar el changelog con Copilot.
5725

5826
---
5927

60-
### 4. Propuesta inicial / decisión
61-
62-
**Opción recomendada**
63-
- **Base**: GitHub Actions + `release-please` por repositorio como mecanismo de versionado y creación de PRs de release.
64-
- **Capa de agentes/skills**:
65-
- Skills locales en cada repo (carpeta `release/`) para:
66-
- Leer `.releaserc.yml` y commits.
67-
- Generar changelog en español.
68-
- Actualizar `package.json` u otros manifests.
69-
- Llamar a un agente de comunicación (notas de release).
70-
- Skills de **orquestación multi‑proyecto** en un repositorio de plataforma (p.ej. `epayco-release-orchestrator`), usando Semantic Kernel u otro orquestador.
71-
- **Trazabilidad unificada**:
72-
- Mantener un formato estándar de eventos JSONL en `release/audit-log.jsonl` (ya iniciado por `release-audit.yml`).
73-
- Publicar estos logs como artifacts y, más adelante, consolidarlos en un lago de datos central.
74-
75-
**Alineación con el contexto de ePayco**
76-
- Reutiliza **GitHub + Actions + release-please**, que ya se utilizan.
77-
- Permite releases **coordinados de múltiples proyectos** sin introducir de inmediato ArgoCD.
78-
- La capa de agentes es incremental: primero documentación y auditoría, luego decisiones más complejas (ventanas de despliegue, orden de servicios, etc.).
28+
### 2. Flujo implementado
29+
30+
```
31+
Developer push (Conventional Commits)
32+
↓
33+
GitHub Actions (.github/workflows/release-please.yml)
34+
↓
35+
release-please detecta commits en master
36+
↓
37+
Crea rama + PR de release ("release v{VERSION}")
38+
↓
39+
Copilot skill — "Documenta el release"
40+
↓
41+
Actualiza release/CHANGELOG.md en español
42+
↓
43+
Merge manual a master
44+
↓
45+
release-please crea tag + GitHub Release
46+
```
47+
48+
**Separación de responsabilidades clara:**
49+
50+
- `release-please` **calcula la versión**, crea la rama, el PR y el tag. No se toca.
51+
- La **skill** (`release/`) solo actualiza `release/CHANGELOG.md` en español con el formato de ePayco. No recalcula versión, no crea tags, no crea PRs adicionales.
7952

8053
---
8154

82-
### 5. Integración con `release-please` y multi‑proyecto
83-
84-
#### 5.1 Patrón por repositorio
85-
86-
1. **release-please**
87-
- Detecta commits en `main/master` y crea PRs con ramas `release/vX.Y.Z`.
88-
- Al hacer merge, genera el **tag** `vX.Y.Z` y, opcionalmente, un GitHub Release.
89-
90-
2. **Skill de release local (`release/`)**
91-
- Se ejecuta (a través de Copilot/agents) sobre la rama `release/vX.Y.Z` para:
92-
- Leer configuración `.releaserc.yml`.
93-
- Generar/actualizar `CHANGELOG.md` en español.
94-
- Actualizar `package.json` (campo `version`) u otros.
95-
- Invocar al agente de comunicación para generar notas.
96-
- Deja el PR listo para revisión y merge.
97-
98-
3. **Auditoría de creación (workflow `release-audit.yml`)**
99-
- Al hacer `push` a `release/v*`, se agrega una línea JSON al archivo `release/audit-log.jsonl` con:
100-
- `service`, `environment` (por defecto `unknown`), `version`, `commit`, `release_branch`, `pipeline_run_id`, `requested_by`, `status="created"`, `timestamp`.
101-
- El archivo se sube como artifact `release-audit-log`.
102-
103-
#### 5.2 Orquestación multi‑proyecto
104-
105-
Para releases que afectan a varios servicios:
106-
107-
- **Repositorio de orquestación**
108-
- Define “sets de release” (por ejemplo, `checkout-core`, `payments-suite`) que son listas de repos/servicios.
109-
- Provee workflows `workflow_dispatch` que:
110-
- Reciben un `release_name` y un entorno (`dev`, `staging`, `prod`).
111-
- Consultan, para cada servicio del set, el último tag `vX.Y.Z` producido por `release-please`.
112-
- Lanzan en cada repo un workflow de `deploy` parametrizado con:
113-
- `version` = tag de `release-please`.
114-
- `environment` = entorno de destino.
55+
### 3. Archivos clave del sistema
11556

116-
- **Workflows de deploy por servicio**
117-
- En cada repo, un `deploy.yml` con:
118-
- Trigger `workflow_dispatch` (llamado desde el orquestador).
119-
- Inputs `version` (tag) y `environment`.
120-
- Deploy al entorno indicado (Kubernetes, VM, etc.).
121-
- Paso de auditoría que añade eventos JSONL como:
122-
- `status="deploy_initiated"`, `deploy_succeeded`, `deploy_failed`, etc.
123-
- `approvers` (tomados de GitHub Environments o revisores del PR).
124-
125-
De esta forma, **el número de release generado por `release-please` se reutiliza en todos los pipelines** (no se recalcula), garantizando que lo que se despliega es exactamente lo que se etiquetó.
57+
| Archivo | Rol |
58+
| -------------------------------------- | -------------------------------------------------------------------- |
59+
| `.github/workflows/release-please.yml` | Dispara `release-please` en cada push a `master` |
60+
| `release-please-config.json` | Configura tipo de release, path del changelog y secciones en español |
61+
| `.release-please-manifest.json` | Fuente de verdad de la versión actual por paquete |
62+
| `release/CHANGELOG.md` | Registro de cambios generado en español (formato ePayco) |
63+
| `release/skill.md` | Descripción funcional de la skill para el agente |
64+
| `release/README.md` | Guía de uso de la skill |
65+
| `.github/copilot-instructions.md` | Instrucciones para Copilot sobre cómo ejecutar la skill |
66+
| `.github/workflows/release-audit.yml` | Registra evento JSONL de auditoría al crear rama `release/v*` |
12667

12768
---
12869

129-
### 6. Gestión de versiones y trazabilidad de cambios
130-
131-
- **Tags y cambios**
132-
- `release-please` es la “fuente de verdad” del versionado; los servicios se despliegan siempre por tag `vX.Y.Z`.
133-
- El changelog se genera en la rama `release/vX.Y.Z` antes del merge, manteniendo una historia clara por versión.
70+
### 4. Secciones del changelog (formato ePayco)
13471

135-
- **Esquema sugerido de evento JSON de auditoría**
136-
- Campos mínimos:
137-
- `service`: nombre del servicio (por ejemplo, `checkout-api`).
138-
- `version`: `vX.Y.Z`.
139-
- `environment`: `dev` | `staging` | `prod` | `unknown`.
140-
- `commit`: SHA principal del release.
141-
- `release_branch`: rama (`release/vX.Y.Z`), si aplica.
142-
- `pipeline_run_id`: identificador del run de GitHub Actions.
143-
- `requested_by`: usuario que disparó la acción.
144-
- `approvers`: lista de usuarios que aprobaron (PR o Environment).
145-
- `status`: `created`, `deploy_initiated`, `deploy_succeeded`, `deploy_failed`, `rollback_initiated`, `rollback_completed`, etc.
146-
- `timestamp`: en formato UTC ISO 8601.
72+
Definidas en `release-please-config.json`:
14773

148-
Este mismo esquema puede usarse tanto en `.github/workflows/release-audit.yml` como en los workflows de `deploy`.
74+
| Tipo de commit | Sección en changelog |
75+
| -------------- | -------------------- |
76+
| `feat` | Características |
77+
| `fix` | Correcciones |
78+
| `docs` | Documentación |
79+
| `refactor` | Refactorización |
80+
| `test` | Pruebas _(oculta)_ |
81+
| `chore` | Tareas _(oculta)_ |
14982

15083
---
15184

152-
### 7. Integración con herramientas de gestión de trabajo
85+
### 5. Auditoría
15386

154-
- **Convenciones en commits**
155-
- Uso de Conventional Commits con referencias a tareas (p.ej. `feat: ... (CU-XXXX)` o `feat: ... (#123)`).
87+
El workflow `release-audit.yml` se activa cuando se crea una rama con patrón `release/v*` y registra un evento JSONL en `release/audit-log.jsonl` con los campos:
15688

157-
- **Skill de “enriquecimiento de release”**
158-
- Dado un `service`, `version` y `environment`, el agente:
159-
- Lista los commits incluidos en la versión (via Git / API de `release-please`).
160-
- Extrae referencias a issues/tickets.
161-
- Llama a las APIs de ClickUp/GitHub Issues para:
162-
- Cambiar estados a “Deployado en X”.
163-
- Registrar comentarios con `version`, `environment` y `pipeline_run_id`.
89+
```json
90+
{
91+
"service": "simple-test-project",
92+
"environment": "unknown",
93+
"version": "vX.Y.Z",
94+
"commit": "<SHA>",
95+
"release_branch": "release/vX.Y.Z",
96+
"pipeline_run_id": "<RUN_ID>",
97+
"requested_by": "<ACTOR>",
98+
"approvers": [],
99+
"status": "created",
100+
"timestamp": "2026-01-01T00:00:00Z"
101+
}
102+
```
164103

165-
Este skill se ejecuta típicamente **después de un deploy exitoso**, enlazando trazabilidad técnica y funcional.
104+
> **Nota:** El patrón `release/v*` del trigger de `release-audit.yml` no coincide con el nombre de rama que genera `release-please` en la configuración actual (`release-please--branches--master--components--*`). Si se estandariza el nombre de rama a `release/vX.Y.Z`, el audit se activará automáticamente.
166105
167106
---
168107

169-
### 8. Recursos y referencias
108+
### 6. Próximos pasos (evolución futura)
170109

171-
- Documentación oficial de **release-please** (GitHub Action).
172-
- **GitHub Actions – Environments & protection rules** para aprobación de despliegues.
173-
- **Argo CD / Argo Workflows** como evolución hacia GitOps si la mayoría de servicios son Kubernetes.
174-
- **Microsoft Semantic Kernel** para definir skills y planners de orquestación de agentes.
175-
- Archivos existentes en este repo:
176-
- `release/skill.md` – descripción de la skill de release local.
177-
- `.github/workflows/release-audit.yml` – ejemplo de evento de auditoría al crear una rama `release/v*`.
178-
179-
---
110+
1. **Estandarizar nombres de ramas de release** a `release/vX.Y.Z` para que `release-audit.yml` se active automáticamente.
180111

181-
### 9. Próximos pasos y pendientes
112+
2. **Extender el modelo de auditoría** con eventos adicionales:
113+
- Aprobación de PR de release.
114+
- Deploy y rollback por entorno (`dev`, `staging`, `prod`).
115+
- Consolidar los JSONL en un repositorio o lago de datos central.
182116

183-
1. **Confirmar contexto**
184-
- Repositorios y plataforma de CI/CD actuales.
185-
- Lista de 2–3 proyectos prioritarios para el primer piloto.
186-
- Requisitos de cumplimiento (campos obligatorios, retención de logs).
117+
3. **Orquestación multi‑proyecto** _(fase futura)_:
118+
- Repositorio de orquestación con "release sets" (listas de servicios que se liberan juntos).
119+
- Workflows `workflow_dispatch` que consultan el tag de `release-please` por servicio y lanzan deploys coordinados.
120+
- Cada repo expone un `deploy.yml` con inputs `version` y `environment`.
187121

188-
2. **Estandarizar `release-please`**
189-
- Alinear naming de tags y ramas (`release/vX.Y.Z`).
190-
- Asegurar que todos los servicios prioritarios usan `release-please` o migrarlos.
122+
4. **Skills adicionales** _(fase futura)_:
123+
- `LinkWorkItemsSkill`: dado un release, extrae referencias a issues/tickets y actualiza su estado en ClickUp/GitHub Issues.
124+
- `RegisterAuditEventSkill`: registra eventos de deploy y rollback en el lago de datos.
191125

192-
3. **Extender el modelo de auditoría**
193-
- Añadir eventos para:
194-
- Aprobaciones de PR de release.
195-
- Deploy y rollback por entorno.
196-
- Definir el repositorio o sistema donde se consolidarán los JSONL.
197-
198-
4. **Crear repositorio de orquestación multi‑proyecto**
199-
- Definir “release sets” y workflows `workflow_dispatch`.
200-
- Exponer inputs claros (`release_name`, `environment`) para humanos y agentes.
201-
202-
5. **Definir y prototipar skills de agentes**
203-
- `AnalyzeReleaseImpactSkill`, `GenerateStakeholderSummarySkill`, `RegisterAuditEventSkill`, `LinkWorkItemsSkill`.
204-
- Decidir si se implementan con Semantic Kernel u otra librería.
126+
---
205127

206-
6. **PoC**
207-
- Aplicar el diseño en 1–3 servicios.
208-
- Ejecutar al menos un release coordinado multi‑proyecto usando el número de release automático de `release-please`.
209-
- Validar que la traza permite responder claramente: **qué versión**, **cuándo**, **en qué entorno** y **con qué aprobaciones**.
128+
### 7. Recursos y referencias
210129

130+
- [Documentación oficial de release-please](https://github.com/googleapis/release-please)
131+
- [GitHub Actions – Environments & protection rules](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)
132+
- Archivos existentes en este repo:
133+
- `release/skill.md` – descripción de la skill de release local.
134+
- `.github/copilot-instructions.md` – instrucciones para Copilot.
135+
- `.github/workflows/release-audit.yml` – evento de auditoría al crear una rama `release/v*`.

0 commit comments

Comments
 (0)