Diagrama de pipeline CI/CD: del commit a producción, paso a paso

Pide un diagrama de CI/CD y normalmente recibirás una fila de cajas: compilar, probar, desplegar. No es incorrecto, pero no responde a casi ninguna de las preguntas con las que la gente llega a él. ¿Qué se despliega exactamente? ¿Quién puede llevar cambios a producción? ¿Dónde están las aprobaciones? ¿Cómo hacemos rollback y qué nos indica que hace falta?

Esta guía muestra cómo dibujar un diagrama de pipeline CI/CD que responda a esas preguntas, tomando como ejemplo una configuración habitual: pull requests al estilo de GitHub, un registro de contenedores y despliegues GitOps en Kubernetes con Argo CD. Las reglas sirven igual para otras herramientas.

Qué debe mostrar un diagrama de pipeline

• Disparadores. Qué inicia cada parte: un pull request, un merge a main, un tag, una ejecución programada.
• Etapas y su orden. Lint, pruebas, build, escaneo, despliegue, verificación.
• Artefactos. Lo que pasa de una etapa a otra, normalmente una imagen de contenedor. Muestra cómo se identifica: con un tag o, mejor aún, con un digest.
• Entornos. Dónde se ejecuta el artefacto y en qué orden llega allí.
• Puntos de control. Aprobaciones manuales, comprobaciones obligatorias y políticas que detienen un cambio.
• Credenciales. Qué sistema puede modificar qué entorno.
• Retroalimentación. Cómo las señales de producción detienen o revierten una versión defectuosa.

Una fila de etapas cubre los dos primeros puntos. El resto es donde ocurren los incidentes y las auditorías.

El ejemplo: GitOps en Kubernetes

1. Un desarrollador abre un pull request en el repositorio de la aplicación.
2. La CI se ejecuta en cada push: lint, pruebas unitarias, build de la imagen y escaneo. Cuando se hace merge a main, sube la imagen al registro y anota su digest.
3. Después, la CI hace commit del nuevo digest de la imagen en el overlay de staging de un repositorio de configuración aparte.
4. Argo CD, en el clúster de staging, detecta el commit, descarga la configuración y sincroniza el clúster.
5. Para promover la versión, alguien abre un pull request que copia la referencia al overlay de producción. Una revisión obligatoria hace de punto de aprobación.
6. Tras el merge, Argo CD sincroniza producción y Argo Rollouts, un controlador independiente dentro del clúster, publica la nueva versión como canary: primero una pequeña parte del tráfico y luego todo.
7. Durante el canary, Argo Rollouts ejecuta un análisis sobre las métricas de Prometheus. Si el análisis falla, se aborta el rollout, el tráfico vuelve a la versión estable y las alertas avisan al ingeniero de guardia.

Hay dos detalles en este diagrama que es fácil pasar por alto y que importan mucho. La CI nunca habla con un clúster: solo sube la imagen al registro y hace commit en Git. Y producción solo cambia mediante un commit revisado, que también es la forma de hacer rollback: reviertes el commit y Argo CD sincroniza la versión anterior.

Push o pull: dibuja dónde viven las credenciales

En un pipeline basado en push, la CI tiene credenciales del clúster y ejecuta ella misma el comando de despliegue. En una configuración GitOps basada en pull, un agente dentro de cada clúster, como Argo CD o Flux, obtiene de Git el estado deseado y lo aplica, así que nada fuera del clúster necesita acceso de escritura a él.

Ambos enfoques son válidos, y el diagrama debe dejar clara la elección. Con push, dibuja una conexión desde la CI hasta cada clúster y etiquétala con la credencial que usa. Con pull, dibuja el repositorio de configuración alimentando al agente de cada clúster, sin ninguna conexión desde la CI hacia un clúster. Así, quien revise verá de un vistazo el radio de impacto de un secreto de CI filtrado.

Si la CI necesita acceso a la nube, por ejemplo para subir imágenes, anota cómo lo obtiene. En un diagrama, los tokens de corta duración mediante OpenID Connect cuentan una historia mucho mejor que una clave de larga duración guardada como secreto.

Reglas para un diagrama de pipeline legible

Haz visible el artefacto

Etiqueta la conexión que entra en el registro con el artefacto y cómo se identifica: image shop-api, by digest. Los tags se pueden mover; un digest siempre apunta a la misma imagen. Si además generas un SBOM o una firma, muéstralos junto a la imagen.

Dibuja los entornos como marcos

Cada entorno es un marco que contiene su agente de despliegue y su clúster. El orden de los marcos muestra el camino de promoción, y cualquier cosa que se salte un marco destaca enseguida.

Dale a cada punto de control su propio nodo

Una aprobación es un paso con un responsable, no una etiqueta sobre una flecha. Dibújala como un nodo entre entornos e indica quién aprueba: approve: release manager o 2 reviews required.

Cierra el ciclo

Un pipeline que termina en "desplegar" no tiene retroalimentación. Dibuja qué vigila producción y qué puede hacer: detener un canary, avisar a una persona, lanzar un rollback.

Deja los detalles de los jobs en el archivo de CI

Doce jobs de pruebas en paralelo pertenecen a la configuración de CI. En el diagrama basta con un nodo de etapa con una etiqueta corta (lint, test, build, scan).

Errores comunes

• Sin artefacto. Cajas unidas por flechas que no transportan nada en concreto. Quien lo lee no sabe qué se promueve.
• Entornos como etapas. "Desplegar en staging" y "desplegar en prod" como dos cajas seguidas ocultan que son lugares distintos con permisos distintos.
• Sin camino de rollback. Si nadie puede señalarlo en el diagrama, probablemente no se ha probado.
• Cada job como un nodo. El diagrama se convierte en el log de la CI.
• Herramientas en lugar de responsabilidades. Una caja con el nombre de un producto dice menos que build and scan image.

Créalo en Archboard

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Desde el pack DevOps, añade nodos Repositorio para el repositorio de la aplicación y el de configuración, y una Canalización para la CI. Añade un Registro del pack Docker.
3. Añade un Marco del pack Básico para cada entorno, con un nodo Despliegue del pack DevOps para Argo CD (y Argo Rollouts en producción) y un Clúster de Kubernetes del pack Nube dentro.
4. Añade una forma Rombo del pack Básico para el punto de aprobación.
5. Añade los nodos Métricas y Alerta del pack DevOps, y nodos Persona del pack Modelo C4 para el desarrollador y el ingeniero de guardia.
6. Conecta los puertos, etiqueta cada conexión con lo que fluye por ella y haz discontinua la conexión de retroalimentación.

El ejemplo usa 15 nodos de diagrama, el límite del plan Free. Para un pipeline con observabilidad integrada, abre /examples/cicd-observability; para la parte del clúster, consulta cómo dibujar un diagrama de arquitectura de Kubernetes.

Preguntas frecuentes

¿Debo dibujar cada job de CI? No. Agrupa los jobs en etapas y deja los detalles en el archivo de CI. Dibuja un job por separado solo cuando sea un punto de control, como un escaneo de seguridad que bloquea la publicación.

¿Cómo muestro los feature flags? Como un sistema aparte junto a producción, con una conexión hacia los servicios que leen los flags. Los flags cambian el comportamiento sin un despliegue, así que merecen su propia línea en el diagrama.

¿Dónde van los secretos en el diagrama? Muestra qué sistema guarda qué credencial y para qué, no los secretos en sí. En el caso de la CI, indica si usa tokens OIDC de corta duración o claves almacenadas.

¿Necesito un diagrama por repositorio? Normalmente, un diagrama por ruta de entrega. Si muchos servicios comparten el mismo pipeline, dibújalo una vez y enumera los servicios en una nota.

¿Cómo mantengo el diagrama al día? Revísalo cuando cambie el pipeline, igual que revisas el archivo de CI. Enlaza el diagrama en vivo desde el README del repositorio para que solo haya una copia.

Empieza gratis — un puesto, sin tarjeta de crédito.