Gestión de Releases: Rastrea Cada Despliegue a Través de Tu Arquitectura
Hace dos meses, participé en un post-mortem donde la pregunta central era engañosamente simple: "¿Qué versión del Servicio de Pagos está corriendo en producción ahora mismo?"
Cuatro personas dieron tres respuestas diferentes. Una revisó la página de releases de GitHub. Otra abrió ArgoCD. Una tercera scrolleó por el canal de despliegues en Slack. La cuarta — la que realmente había desplegado — estaba de vacaciones.
No era una startup. Era un equipo con un pipeline CI/CD maduro, buenas prácticas de tagging, y un diagrama de arquitectura bien mantenido en Archyl. El diagrama decía exactamente qué sistemas existían, cómo estaban conectados, qué protocolos usaban. Simplemente no podía decir qué versión de cualquier cosa estaba corriendo realmente. En ningún lado.
Esa brecha me molesta desde hace tiempo. La documentación de arquitectura te dice la estructura de un sistema. El historial de despliegues te dice el estado de un sistema. Estas dos cosas deberían vivir juntas. A partir de hoy, lo hacen.
Releases Vinculadas a la Arquitectura
La gestión de releases de Archyl rastrea los despliegues como objetos de primera clase en tu espacio de arquitectura. Una release tiene una versión, un estado, un entorno, un changelog, y — crucialmente — un vínculo con el elemento C4 al que pertenece.
Esa última parte es lo que la diferencia de tu dashboard de CI/CD. Un run de GitHub Actions te dice que v2.4.0 fue desplegada. Pero desplegada dónde, en el contexto de tu arquitectura? ¿Qué sistema? ¿Qué contenedor? Las releases de Archyl responden vinculando los eventos de despliegue directamente a los sistemas y contenedores de tu diagrama C4.
Cuando abres el panel de detalle de un sistema, ves sus releases recientes junto a sus relaciones, ADRs y contratos de API. El diagrama de arquitectura se convierte en un mapa vivo — no solo de lo que existe, sino de lo que se desplegó y cuándo.
Tres Formas de Ingesta
No queríamos que el seguimiento de releases significara más trabajo manual. Si ya estás desplegando a través de un pipeline, las releases deberían llegar a Archyl automáticamente.
GitHub Actions — Publicamos una GitHub Action oficial que agregas a tu workflow de despliegue. Un setup mínimo son dos líneas en tu YAML. La action envía la versión, el SHA del commit, el entorno y el changelog a Archyl en cada despliegue exitoso. También soporta campos personalizados — vincular a un sistema o contenedor específico, definir el estado, incluir el autor.
- uses: archyl/release-action@v1
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
version: ${{ github.ref_name }}
Eso es todo. Cada release tagueada ahora aparece en tu espacio de arquitectura.
Webhooks — Configura un endpoint de webhook en los ajustes de tu proyecto, luego apunta los webhooks de release de GitHub o GitLab hacia él. Cuando se publica una nueva release o se pushea un tag, Archyl recibe el evento y crea una entrada de release automáticamente. Puedes definir un patrón de tag (ej. v*) para filtrar qué tags crean releases, y asignar un entorno por defecto para que las releases creadas por webhook lleguen al lugar correcto.
API REST — Para equipos usando Jenkins, CircleCI, Bitbucket Pipelines o cualquier otra herramienta CI/CD, el endpoint de ingesta acepta un payload JSON simple. Autentica con una clave API, envía la versión y los metadatos, y la release aparece en Archyl. Esta es la solución universal — si tu herramienta puede hacer una petición HTTP, puede reportar releases.
Los tres métodos se configuran en los ajustes del proyecto bajo la pestaña Releases, con snippets de código copiables y claves API auto-completadas.
Entornos
No todos los despliegues son iguales. Pushear a staging es rutina. Pushear a producción es un evento. La gestión de releases rastrea ambos, por separado.
Los entornos son definidos por el usuario y tienen un código de color. Crea "Development", "Staging", "Production" — o lo que tu equipo use. Cada release se etiqueta con su entorno destino, y puedes filtrar la timeline para ver solo despliegues a producción, o solo lo que está en staging ahora mismo.
El modelo de entornos es flexible. Un equipo gestionando un solo servicio podría tener dos entornos. Un equipo de plataforma gestionando cuarenta microservicios podría tener cinco. Tú defines lo que tiene sentido para tu proyecto, y las releases se organizan en consecuencia.
La Timeline
La timeline de releases es la vista principal. Las releases se agrupan por mes, mostradas en orden cronológico inverso, con badges de versión, tags de entorno e indicadores de estado. Es la respuesta a "¿qué pasó recientemente?" — de un vistazo.
Cada entrada de release muestra:
- Versión — El tag semver o identificador (ej.
v2.4.0,3.12.0-rc.2) - Estado — Deployed, In Progress, Planned, Failed o Rolled Back
- Entorno — Badge con color (Production, Staging, etc.)
- Elemento vinculado — El sistema o contenedor al que pertenece esta release
- Fuente — De dónde vino la release (GitHub Action, webhook, API, manual)
- Changelog — Qué cambió, quién lo escribió, información de signed-off-by
Haz clic en cualquier release para abrir su panel de detalle con el changelog completo, fechas (creada, desplegada, actualizada), elementos C4 impactados y un enlace a la fuente (commit, página de release de GitHub, etc.).
La Matriz de Despliegues
Para equipos gestionando múltiples servicios a través de múltiples entornos, construimos una segunda vista: la Matriz de Despliegues.
Es una cuadrícula donde las filas son tus sistemas y contenedores, las columnas son tus entornos, y cada celda muestra la última release desplegada para esa combinación. De un vistazo, puedes ver que la Account API está en v3.1.0 en producción pero en v3.2.0-beta en staging. O que el Notification Service no se ha desplegado a producción en tres semanas.
La matriz hace visible la deriva de entornos. Cuando las versiones de staging y producción divergen, lo detectas inmediatamente. Cuando un servicio se queda atrás mientras otros avanzan, la brecha es obvia.
Ciclo de Vida de Estados
Las releases no siempre son limpias. Los despliegues fallan. Las releases se revierten. Rastreamos el ciclo de vida completo:
- Planned — La release existe pero aún no fue desplegada. Útil para rastrear versiones próximas.
- In Progress — El despliegue está en curso. Se define automáticamente por las integraciones CI/CD durante el paso de despliegue.
- Deployed — La release está live en su entorno destino. El camino feliz.
- Failed — El despliegue no tuvo éxito. La entrada de release queda como registro de lo que se intentó.
- Rolled Back — La release fue desplegada pero posteriormente revertida. Esto preserva el historial — puedes ver que
v2.3.1fue rollbackeada, cuándo y por qué.
Las transiciones de estado son automáticas con integraciones CI/CD, o manuales al crear releases desde la interfaz.
Vinculación a Elementos de Arquitectura
Cada release puede vincularse a un sistema, un contenedor, o ambos. Esto es lo que da a las releases su contexto arquitectónico.
En los ajustes del proyecto, configuras un destino de vinculación por defecto — el sistema y opcionalmente un contenedor donde las releases se adjuntarán. Los snippets de código para GitHub Actions, webhooks y la API REST se actualizan automáticamente para incluir los IDs de elementos correctos.
En el diagrama, los elementos vinculados muestran su historial de releases en el panel de detalle. Haz clic derecho en un contenedor y verás no solo sus relaciones y contratos, sino también su timeline de despliegues. Es donde la documentación de arquitectura y la realidad operacional convergen.
Por Qué Importa
Los diagramas de arquitectura siempre han sido una foto fija. Te muestran lo que el sistema es — las cajas, las flechas, los protocolos. Pero no muestran lo que el sistema está haciendo. ¿Ese servicio está en la última versión? ¿Cuándo fue el último despliegue? ¿Alguien revirtió la release del martes pasado?
Son preguntas que surgen en cada revisión de arquitectura, cada respuesta a incidentes, cada onboarding. Y hasta ahora, la respuesta siempre era "revisa la herramienta de CI/CD" o "pregúntale al equipo que lo gestiona."
La gestión de releases pone el historial de despliegues donde debe estar: en la arquitectura misma. Cuando alguien pregunta "¿qué versión está corriendo en el Payment Gateway?", la respuesta está ahí en el diagrama — no en una herramienta diferente, no en otra pestaña, no en la cabeza de alguien.
Es la misma filosofía detrás de los Contratos de API y los ADRs: la documentación de arquitectura debería responder preguntas reales que surgen cada día, no solo describir estructura en abstracto.
Para Empezar
Navega a los Ajustes de tu proyecto y abre la pestaña Releases. Elige tu método de integración — GitHub Action, webhooks o API REST — y sigue la guía de configuración. Crea tus entornos, vincula un sistema o contenedor destino, y lanza tu primera release.
A partir de ahí, cada despliegue llega automáticamente a tu espacio de arquitectura. Tus diagramas C4 dejan de ser planos estáticos y se convierten en un registro vivo de lo que realmente está corriendo.
Tu arquitectura es más que estructura. Ahora tus herramientas lo reflejan.
¿Quieres aprender más sobre cómo conectar tu arquitectura con la realidad? Descubre cómo los Contratos de API vinculan tus specs al diagrama, o cómo las Solicitudes de Cambio de Arquitectura traen flujos de pull request a tu modelo C4.