Gestión de Releases

La Gestión de Releases rastrea los despliegues como objetos de primera clase en tu espacio de arquitectura. Cada release está vinculada a un elemento C4, dando a tus diagramas una vista en vivo de lo que realmente está corriendo.

Conceptos Fundamentales

Releases

Una release representa una versión específica desplegada en un entorno. Cada release tiene:

Entornos

Los entornos representan destinos de despliegue. Son definidos por el usuario y tienen código de color.

Configuraciones comunes:

• Development → Staging → Production
• Dev → QA → Pre-prod → Production

Crea tantos entornos como tu workflow requiera. Cada release se etiqueta con su entorno destino.

Ciclo de Vida de Estados

Las releases pasan por estos estados:

Configurar el Seguimiento de Releases

1. Crear Entornos

1. Ve a los Ajustes de tu proyecto
2. Abre la pestaña Releases
3. Bajo Entornos, haz clic en Agregar Entorno
4. Ingresa un nombre y elige un color
5. Arrastra para reordenar los entornos por etapa de despliegue

2. Configurar un Destino de Vinculación por Defecto

Define el sistema y opcionalmente un contenedor donde las releases se adjuntarán por defecto:

1. En la pestaña Releases de los ajustes, encuentra Destino de Vinculación por Defecto
2. Selecciona un sistema del menú desplegable
3. Opcionalmente selecciona un contenedor dentro de ese sistema
4. Este destino se usa cuando las releases ingresadas no especifican un elemento

3. Elegir un Método de Integración

Archyl soporta tres formas de ingestar releases automáticamente.

Métodos de Integración

GitHub Actions

Agrega la GitHub Action oficial de Archyl a tu workflow de despliegue.

Configuración mínima:

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}

Configuración completa:

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}
    environment: production
    system-id: <your-system-uuid>
    container-id: <your-container-uuid>
    changelog: "Correcciones de bugs y mejoras de rendimiento"
    status: deployed

La action envía la versión, el SHA del commit, el entorno y el changelog a Archyl en cada despliegue exitoso.

Webhooks

Configura la ingesta por webhook para recibir eventos de release desde GitHub o GitLab.

1. En la pestaña Releases de los ajustes, activa los Webhooks
2. Copia la URL del webhook mostrada
3. En GitHub o GitLab, agrega un nuevo webhook apuntando a esa URL
4. Selecciona el tipo de evento Release o Tag push

Opciones de configuración:

Cuando se publica una nueva release o se pushea un tag que coincida, Archyl crea automáticamente una entrada de release.

API REST

Para cualquier herramienta CI/CD que pueda hacer peticiones HTTP — Jenkins, CircleCI, Bitbucket Pipelines o pipelines personalizados.

Endpoint: POST /api/v1/projects/:projectId/releases

Headers:

Authorization: Bearer <api-key>
Content-Type: application/json

Payload:

{
  "version": "v2.4.0",
  "status": "deployed",
  "changelog": "Agregada lógica de reintentos para pagos",
  "environmentId": "<environment-uuid>",
  "systemId": "<system-uuid>",
  "containerId": "<container-uuid>",
  "sourceUrl": "https://github.com/org/repo/releases/tag/v2.4.0"
}

La pestaña de ajustes muestra snippets de código copiables con claves API e IDs de elementos auto-completados.

Vistas

Timeline de Releases

La vista principal. Las releases se agrupan por mes en orden cronológico inverso. Cada entrada muestra:

• Badge de versión
• Indicador de estado
• Tag de entorno (código de color)
• Sistema o contenedor vinculado
• Fuente (GitHub Action, webhook, API, manual)
• Marca de tiempo relativa

Haz clic en cualquier release para abrir su panel de detalle con el changelog completo, fechas y un enlace a la fuente.

Filtrado:

• Por entorno (ej. mostrar solo despliegues a producción)
• Por estado (ej. mostrar solo despliegues fallidos)
• Por elemento vinculado

Matriz de Despliegues

Una vista en cuadrícula para equipos gestionando múltiples servicios a través de múltiples entornos.

• Filas — Sistemas y contenedores
• Columnas — Entornos
• Celdas — Última release desplegada para esa combinación

La matriz hace visible la deriva de entornos de un vistazo. Cuando las versiones de staging y producción divergen, lo detectas inmediatamente.

Vincular Releases a la Arquitectura

Cada release puede vincularse a un sistema, un contenedor, o ambos.

Vinculación Automática

Con GitHub Actions o webhooks, las releases se vinculan al destino por defecto configurado en los ajustes. Puedes sobrescribir el destino por release especificando system-id y container-id.

Vinculación Manual

Al crear una release desde la interfaz:

1. Haz clic en Nueva Release
2. Completa la versión, el estado y el changelog
3. Selecciona el sistema y/o contenedor destino
4. Elige el entorno
5. Haz clic en Crear

Visualización en el Diagrama

Haz clic derecho en cualquier elemento del diagrama C4 para abrir su panel de detalle. Las releases vinculadas aparecen en la sección Releases junto a las relaciones, ADRs y contratos de API. El elemento muestra su versión de release más reciente y su entorno.

Crear Releases Manualmente

No todas las releases vienen de un pipeline. Para crear una release a mano:

1. Navega a la pestaña Releases
2. Haz clic en Nueva Release
3. Ingresa la versión, selecciona un estado y un entorno
4. Escribe un changelog (markdown soportado)
5. Vincula a un sistema y/o contenedor
6. Haz clic en Crear

Las releases manuales tienen su fuente marcada como Manual en la timeline.

Buenas Prácticas

Usa Versionado Semántico

• Etiqueta las releases con semver (ej. v1.2.3)
• Incluye identificadores de pre-release para despliegues fuera de producción (ej. v2.0.0-rc.1)
• Mantén las cadenas de versión consistentes entre entornos

Rastrea Todos los Entornos

• Crea entornos para cada etapa de despliegue
• No omitas staging — la matriz de despliegues es más útil cuando muestra el pipeline completo
• Usa la vista de matriz para detectar la deriva de entornos tempranamente

Automatiza la Ingesta

• Usa GitHub Actions o webhooks en lugar de la entrada manual
• Configura la integración una vez y cada despliegue llega automáticamente
• Reserva la creación manual para hotfixes o despliegues excepcionales

Escribe Changelogs

• Incluye un changelog significativo con cada release
• Resume qué cambió y por qué
• Enlaza a las issues o pull requests relacionadas cuando sea posible

Vincula al Nivel Correcto

• Vincula a sistemas al desplegar una aplicación completa
• Vincula a contenedores al desplegar servicios individuales dentro de un sistema
• Sé consistente — elige una convención y respétala

Próximos Pasos

• Contratos de API — Documenta tus especificaciones de API
• Insights de Arquitectura — Detecta problemas arquitectónicos
• Solicitudes de Cambio de Arquitectura — Propón cambios a través de un flujo de revisión