GitHub Actions: CI/CD fiable y mantenible
Publicado el · Actualizado el
GitHub actions permite automatizar validación, pruebas, builds, packaging, tareas programadas y despliegues desde eventos del repositorio. Esta guía explica cómo diseñar CI/CD fiable, proteger secrets, separar entornos, optimizar tiempo, desplegar artifacts probados, diagnosticar fallos y mantener el pipeline.
Diseña el workflow antes del YAML
Antes de escribir YAML, describe el recorrido desde un cambio hasta una versión probada y desplegada. Define branches, checks de pull request, instalación, lint, type checking, tests, build, packaging, destinos de despliegue y aprobaciones manuales. Este mapa es más útil que un archivo largo porque expone dependencias. Decide qué corre en cada PR, qué ocurre solo después del merge y qué tareas deben mantenerse manuales o programadas.
Separa CI y CD conceptualmente. CI responde si el cambio puede fusionarse con seguridad. CD define qué pasa después: empaquetar, desplegar, ejecutar migraciones, comprobar salud y promover entre entornos. Esta distinción hace que los fallos sean más fáciles de interpretar.
Define entradas y salidas de cada job. Build recibe código y lockfile y genera un artifact. Deployment consume ese artifact y credenciales del entorno. Contratos claros simplifican cache, reutilización y diagnóstico.
- Map release flow
- Separate CI and CD
- Define job inputs
- Document assumptions
Elige triggers que reflejen el proceso
Usa solo eventos que correspondan al flujo real. pull_request sirve para validación previa, push para acciones posteriores al merge, schedule para mantenimiento y workflow_dispatch para ejecución manual controlada. Los filtros de path pueden ahorrar trabajo, pero deben evitar saltarse pruebas relevantes.
Production no debería desplegar desde cualquier feature branch. Define qué branches o tags pueden crear releases y qué representa cada tag. Reglas ambiguas producen ejecuciones duplicadas o versiones incorrectas en el entorno equivocado.
Controla concurrency. En CI, commits nuevos pueden volver obsoletos runs anteriores. En deployment, normalmente interesa permitir un solo despliegue por entorno a la vez. Trigger y concurrencia deben diseñarse juntos.
- Use focused triggers
- Protect release refs
- Manage concurrency
- Avoid duplicate runs
Construye un CI reproducible
Un CI fiable empieza con un entorno reproducible. Fija la versión del runtime, usa lockfile y evita depender de herramientas implícitas del runner. Los comandos locales y los de CI deberían ser similares para que un error pueda reproducirse fuera de GitHub.
Ejecuta primero checks rápidos. Format, lint y análisis estático suelen terminar antes que integración o builds grandes. Divide tests cuando la paralelización tenga valor real, pero evita fragmentar el pipeline hasta hacerlo difícil de leer.
Los criterios de éxito deben ser explícitos. Un build verde que no ejecutó pruebas importantes no demuestra nada. Las órdenes deben fallar cuando corresponde, los artifacts deben verificarse y las migraciones deberían probarse antes de producción.
- Pin runtime
- Fail fast
- Parallelize carefully
- Validate outputs
Protege secrets y entornos
No guardes secrets en YAML, código ni logs. Usa secrets cifrados de repositorio, organización o environment con el alcance mínimo. Un credential de producción no debería estar disponible para todos los jobs de pull request. Cuando sea posible, usa identidad de corta duración.
Los environments separan staging y producción con variables, approvals e historial. Esto evita que un job de prueba obtenga permisos de producción automáticamente. Nombra endpoints, regiones y project IDs de forma inequívoca.
Los logs también pueden filtrar información. Debug verbose, echo o acciones externas pueden imprimir valores sensibles. Revisa la salida, rota credenciales si existe sospecha de exposición y elimina secretos que ya no se usan.
- Scope secrets
- Separate environments
- Protect logs
- Rotate credentials
Optimiza cache, artifacts y matrices
Cache acelera instalación de dependencias, pero no debe convertirse en una fuente de verdad. La clave debe depender del lockfile u otros archivos reales. Si aparece un fallo extraño, debe ser sencillo ejecutar sin cache para descartar datos obsoletos.
Artifacts permiten mover resultados entre jobs y conservar packages, informes, coverage o capturas. Define retention y evita datos sensibles. El deployment debería usar exactamente el artifact que pasó CI en lugar de reconstruir de manera diferente.
Matrix jobs prueban versiones, sistemas o configuraciones. Son útiles si representan compatibilidad real, pero multiplican tiempo y coste. Empieza por combinaciones soportadas y separa escenarios experimentales de checks obligatorios.
- Cache safely
- Use artifacts
- Control retention
- Keep matrices intentional
Automatiza despliegues con control
Automatiza deployment promoviendo un artifact conocido. Registra commit SHA, versión, entorno y hora. Así cualquier incidente puede relacionarse con una release concreta y se evita la incertidumbre de builds diferentes entre etapas.
Aplica controles según el riesgo. Staging puede ser automático y producción requerir approval o tag. Las migraciones de base merecen atención especial porque revertir datos es más difícil que revertir código. Cambios compatibles y backups reducen riesgo.
Después de desplegar, ejecuta smoke tests o health checks contra el entorno real. Decide antes qué ocurrirá si fallan: rollback, parada para decisión o corrección hacia adelante. La recuperación forma parte del diseño del CD.
- Promote tested artifacts
- Use approvals
- Run health checks
- Plan recovery
Haz visibles y explicables los fallos
Nombra jobs y steps de forma descriptiva. Un fallo en Test API es más claro que uno en Run command. Publica informes o annotations para reducir tiempo de lectura. En fallos intermitentes captura runtime, dependencias y servicio externo implicado.
Distingue error de código e infraestructura. Assertion, registry caído, credential expirado, rate limit o runner saturado requieren respuestas diferentes. Usa retry solo para fallos transitorios, no para ocultar errores deterministas.
Mide duración, queue time, tasa de error y jobs lentos. Estas métricas muestran dónde espera el equipo y qué partes son inestables. Para deployment, conserva historial y relación con incidentes.
- Name steps clearly
- Classify failures
- Use targeted retries
- Track metrics
Mantén y evoluciona el pipeline
Mantén el YAML legible. Extrae lógica repetida a reusable workflows, composite actions o scripts si reduce duplicación sin ocultar el proceso. Fija acciones externas a versiones confiables y revisa actualizaciones como cualquier dependencia de seguridad.
Revisa el pipeline cuando cambie la arquitectura. Nuevos servicios, monorepo, entornos o destinos pueden exigir otra organización. Elimina jobs y secrets obsoletos solo después de confirmar que no existen dependencias activas.
Prueba periódicamente el recovery. Debes poder diagnosticar un despliegue fallido, restaurar un artifact anterior cuando sea adecuado y rotar credenciales sin romper todo. Un pipeline maduro permanece comprensible, reproducible y observable.
Revisa también los permisos del token del workflow. Un job que no necesita escribir releases, packages o contenido del repositorio no debería tener esos derechos. Permisos explícitos reducen el impacto de una action externa comprometida. Pull requests desde forks requieren cuidado porque los secrets suelen estar restringidos deliberadamente.
En monorepos, evita ejecutar todo si solo cambia un paquete independiente, pero mantén una detección conservadora. Cambios en lockfile, configuración raíz o código compartido pueden requerir checks más amplios.
Guarda metadata de release como versión, digest del artifact, commit, entorno e identificador de migración cuando sea útil. Esto mejora mucho el análisis de incidentes.
Revisa también los permisos del token del workflow. Un job que no necesita escribir releases, packages o contenido del repositorio no debería tener esos derechos. Permisos explícitos reducen el impacto de una action externa comprometida. Pull requests desde forks requieren cuidado porque los secrets suelen estar restringidos deliberadamente.
En monorepos, evita ejecutar todo si solo cambia un paquete independiente, pero mantén una detección conservadora. Cambios en lockfile, configuración raíz o código compartido pueden requerir checks más amplios.
- Keep workflows readable
- Review third-party actions
- Remove obsolete logic carefully
- Test recovery
Preguntas
¿Para qué sirve github actions?
Para automatizar checks, tests, builds, tareas programadas y despliegues desde eventos del repositorio.
¿Desplegar producción con cada push?
Normalmente no. Usa branches, tags, environments o approvals controlados.
¿Dónde guardar secrets?
En secrets cifrados o identidad de corta duración con alcance mínimo.
¿Qué debe conservar un pipeline fiable?
Commit o artifact validado, logs claros, historial de deployment, entornos separados y una ruta de recuperación.