Tu Primer Pipeline CI/CD en Google Cloud Build: Tutorial cloudbuild.yaml y gcloud CLI
Construir tu primer pipeline CI/CD en Google Cloud no debería consistir en copiar un YAML y esperar que funcione. El objetivo real es entender el modelo de ejecución, separar build, test y release, controlar permisos, gestionar artefactos correctamente y dejar una base que pueda evolucionar desde un primer proyecto GCP hasta una plataforma empresarial de entrega continua.
¿Qué estás construyendo realmente con Cloud Build?
Google Cloud Build ejecuta pasos de construcción dentro de un pipeline gestionado. Cada paso utiliza una imagen de contenedor y puede realizar una tarea concreta: instalar dependencias, ejecutar tests, construir una imagen, ejecutar validaciones o publicar un artefacto.
La ventaja arquitectónica aparece cuando dejas de pensar en “un script que compila mi aplicación” y empiezas a pensar en una cadena reproducible de transformaciones de software.
El flujo base
Source → Build → Test → Package → Registry → Deploy
En este tutorial empezaremos por los primeros cinco bloques. El despliegue se mantiene desacoplado para que la misma imagen inmutable pueda promocionarse posteriormente entre entornos.
¿Dónde encaja Cloud Build en un pipeline GCP?
No todos los proyectos necesitan la misma estrategia. La decisión correcta depende de la complejidad del pipeline, del sistema de control de versiones, del nivel de automatización requerido y de dónde quieres concentrar la gobernanza.
| Patrón | Latencia operativa | Complejidad | Coste | Mejor uso |
|---|---|---|---|---|
| gcloud builds submit | Baja | Baja | Bajo | Primer proyecto, pruebas y desarrollo local |
| Cloud Build Trigger | Baja | Media | Bajo/medio | CI automática asociada al repositorio |
| Build + Artifact Registry | Baja | Media | Medio | CI empresarial y promoción de artefactos |
| CI/CD + despliegue automatizado | Muy baja | Alta | Variable | Plataformas de producción y múltiples entornos |
Para empezar, gcloud builds submit es deliberadamente simple: envías el código y el archivo de configuración a Cloud Build. Para producción, el mismo modelo puede evolucionar hacia triggers, repositorios de artefactos, controles IAM y promoción entre entornos.
El error más caro: confundir CI con despliegue
⚠️ Antipatrón: construir y desplegar directamente a producción en cada commit
Un pipeline inicial puede funcionar perfectamente y, aun así, estar mal diseñado. El problema aparece cuando cada ejecución recompila el software, genera una imagen mutable y la despliega directamente a producción.
El patrón más robusto es separar build de promotion/deployment. Construye una vez, publica un artefacto identificable y promociona ese mismo artefacto.
Esto mejora reproducibilidad, rollback, auditoría y control del coste computacional. Además, Artifact Registry está diseñado para almacenar y gestionar artefactos de software, incluyendo imágenes de contenedor.
Tu primer cloudbuild.yaml funcional
Supongamos una aplicación Docker sencilla. El pipeline tendrá cuatro responsabilidades: ejecutar tests, construir la imagen, publicarla en Artifact Registry y declarar explícitamente la imagen resultante.
substitutions:
_REGION: europe-west1
_REPOSITORY: demo-repo
_IMAGE: demo-app
steps:
# 1. Ejecutar tests antes de generar el artefacto
- name: 'python:3.12-slim'
entrypoint: 'bash'
args:
- '-c'
- |
python -m pip install --no-cache-dir -r requirements.txt
python -m pytest
# 2. Construir la imagen Docker
- name: 'gcr.io/cloud-builders/docker'
args:
- 'build'
- '-t'
- '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}:$BUILD_ID'
- '.'
# 3. Publicar el artefacto inmutable
- name: 'gcr.io/cloud-builders/docker'
args:
- 'push'
- '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}:$BUILD_ID'
images:
- '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPOSITORY}/${_IMAGE}:$BUILD_ID'Observa una decisión importante: la etiqueta utiliza $BUILD_ID en lugar de una etiqueta genérica como latest. El identificador de build proporciona una referencia concreta para rastrear qué ejecución produjo cada imagen.
Ejecutar el pipeline con gcloud
Una vez creado el repositorio de Artifact Registry y configurado el proyecto, puedes lanzar el pipeline desde el directorio raíz del proyecto.
# Seleccionar el proyecto activo
gcloud config set project TU_PROJECT_ID
# Verificar el proyecto
gcloud config get-value project
# Crear el repositorio de imágenes si todavía no existe
gcloud artifacts repositories create demo-repo \
--repository-format=docker \
--location=europe-west1
# Ejecutar Cloud Build usando cloudbuild.yaml
gcloud builds submit \
--region=europe-west1 \
--config=cloudbuild.yaml \
.La forma general documentada para ejecutar una configuración es gcloud builds submit --config=BUILD_CONFIG SOURCE. Usar . indica que el código fuente se encuentra en el directorio actual.
Haz que cloudbuild.yaml sea reutilizable
Una de las primeras mejoras respecto a un YAML de laboratorio es eliminar valores hardcodeados. Cloud Build ofrece sustituciones integradas como $PROJECT_ID y $BUILD_ID, además de variables definidas por el usuario.
Principio de diseño
Si el mismo pipeline debe ejecutarse en distintos proyectos o regiones, el YAML no debería tener que cambiar. Parametriza aquello que representa configuración y deja fija la lógica del pipeline.
En el ejemplo, _REGION, _REPOSITORY y _IMAGE son sustituciones definidas por el usuario.
gcloud builds submit \
--region=europe-west1 \
--config=cloudbuild.yaml \
--substitutions=_REGION=europe-west1,_REPOSITORY=demo-repo,_IMAGE=demo-app \
.Buenas prácticas para evolucionar hacia producción
Artefactos inmutables
Construye una vez y utiliza una referencia identificable para cada versión. Evita depender de latest como mecanismo de promoción.
Least Privilege
El pipeline debe disponer únicamente de los permisos que necesita. Separa permisos de construcción, publicación y despliegue cuando la arquitectura lo requiera.
Observabilidad
Cada ejecución debe poder responder tres preguntas: qué código se construyó, qué artefacto produjo y cuánto tardó cada etapa.
Tests antes del push
Si una validación puede ejecutarse antes de construir la imagen, hazlo. Evitas consumir recursos de build para artefactos que ya sabes que son inválidos.
Separación de entornos
Desarrollo, staging y producción deberían representar políticas diferentes, no simplemente carpetas diferentes dentro del mismo pipeline.
Provenance
Para escenarios empresariales, incorpora controles de procedencia y seguridad de la cadena de suministro para poder demostrar cómo se generó un artefacto.
De primer pipeline a plataforma CI/CD
El salto arquitectónico no consiste en añadir cientos de líneas al YAML. Consiste en introducir fronteras claras entre responsabilidades.
Commit → Trigger → Validate → Build → Artifact Registry → Security / Policy → Promotion → Deployment
Esta separación permite introducir aprobaciones, validaciones de seguridad, políticas de despliegue, rollback y diferentes estrategias de promoción sin convertir el pipeline en un script monolítico.
Framework de implementación paso a paso
Crear o seleccionar el proyecto GCP
Define claramente el proyecto donde se ejecutará Cloud Build y evita mezclar recursos de desarrollo y producción sin una estrategia de gobernanza.
Habilitar los servicios necesarios
Activa Cloud Build, Artifact Registry y los servicios de runtime que necesite tu aplicación.
Crear el repositorio de artefactos
Define región, formato, convenciones de naming y política de retención antes de automatizar el pipeline.
Implementar cloudbuild.yaml
Mantén cada paso pequeño, explícito y observable. Un pipeline legible es más fácil de depurar y gobernar.
Ejecutar con gcloud
Valida primero el pipeline manualmente con gcloud builds submit antes de conectarlo a triggers automáticos.
Automatizar el trigger
Cuando el flujo sea estable, conecta el pipeline al sistema de control de versiones y define claramente qué ramas o eventos provocan una ejecución.
Separar promoción y despliegue
El artefacto generado por CI debe poder promocionarse entre entornos sin recompilar el software.
Añadir seguridad y FinOps
Revisa IAM, procedencia, escaneo, logs, tiempos de build, uso de workers y retención de artefactos.
Checklist de revisión antes de producción
❌ ¿Usas latest?
Si no puedes identificar de forma inequívoca qué build generó la imagen, tienes un problema de trazabilidad.
❌ ¿El build tiene demasiadas responsabilidades?
Si compila, publica, modifica infraestructura y despliega múltiples entornos en una única etapa, considera separar responsabilidades.
❌ ¿IAM demasiado permisivo?
No otorgues permisos amplios simplemente para hacer desaparecer un error de autorización. Identifica primero qué principal necesita qué permiso.
❌ ¿Builds demasiado lentos?
Revisa dependencias, contexto Docker, cachés, tamaño de imágenes y pasos que pueden ejecutarse antes de consumir recursos de build.
❌ ¿Logs sin gobernanza?
Define una estrategia de almacenamiento y acceso a logs compatible con las necesidades de observabilidad y cumplimiento.
❌ ¿Recompilas por entorno?
Siempre que sea posible, promueve el mismo artefacto entre entornos en lugar de generar una imagen diferente para cada destino.
Preguntas frecuentes sobre Google Cloud Build
¿Qué es cloudbuild.yaml y para qué sirve?
cloudbuild.yaml es el archivo de configuración declarativa de Cloud Build. Define los pasos que el servicio ejecutará para tareas como instalar dependencias, ejecutar tests, construir imágenes y publicar artefactos. El campo steps contiene las operaciones principales del pipeline.
¿Cómo ejecuto mi primer pipeline de Cloud Build desde gcloud CLI?
Desde el directorio del proyecto puedes utilizar gcloud builds submit --config=cloudbuild.yaml .. Para una configuración regional explícita puedes añadir --region. Antes de ejecutarlo debes tener correctamente configurado el proyecto, los servicios requeridos y los permisos IAM correspondientes.
¿Por qué debería usar Artifact Registry con Cloud Build?
Artifact Registry proporciona almacenamiento gestionado para artefactos como imágenes de contenedor y se integra directamente con Cloud Build. Esto permite separar la generación del artefacto de su posterior promoción o despliegue, además de facilitar trazabilidad y controles de seguridad.