Guía paso a paso para implementar CI/CD con GitHub Actions en proyectos PHP/Laravel

Por · Publicado el · Actualizado el · 9 min de lectura

Portátil sobre mesa con editor de código abierto en la pantalla y monitor al fondo
Área de trabajo con código en pantalla, adecuada para guías de CI/CD y workflows Foto: yeiferr / Pixabay

Esta guía paso a paso muestra cómo implementar CI/CD con GitHub Actions en proyectos PHP/Laravel. Entenderás triggers, jobs, caché, pruebas, seguridad de secrets y estrategias de despliegue para staging y producción. Al final tendrás un plan claro para configurar un pipeline fiable, con consejos prácticos de mantenimiento y rollback.

Visión general del pipeline y prerequisitos

CI/CD integra validaciones automáticas en cada cambio y entrega versiones de forma predecible. En Laravel, el pipeline suele incluir instalación de dependencias, build de assets, pruebas y despliegue con comandos artisan.

Define el objetivo del pipeline antes de escribir cualquier workflow. Decide qué se ejecuta en cada branch, cuándo se requiere aprobación manual y cómo será el despliegue a staging y producción.

Estandariza versiones de PHP y extensiones. Documenta las dependencias del sistema. Confirma la base de datos necesaria para las pruebas. Evita sorpresas en el runner.

Crea entornos previsibles. Usa variables, secrets y un proceso de versionado consistente. Esto reduce diferencias entre tu máquina y el CI.

  • Acceso al repositorio en GitHub y ramas principales definidas.
  • composer.json y composer.lock versionados.
  • phpunit.xml configurado y pruebas que se ejecutan de segundos a pocos minutos.
  • Servidor o PaaS para despliegue vía SSH, API o container registry.
  • Base de datos de pruebas provisionada (MySQL, PostgreSQL o SQLite).
  • Estrategia de versionado y releases definida.

Prepara el proyecto: Composer, scripts y entornos

Asegúrate de que composer.lock esté versionado. Esto hace los builds reproducibles. Instala las extensiones mínimas y desactiva Xdebug en el CI para acelerar el pipeline.

Crea scripts en composer.json para estandarizar comandos. Centraliza pruebas, linters y análisis estático. Así, el CI solo llama scripts ya usados localmente.

Mantén .env.example completo. Sirve de base para generar entornos de prueba. Nunca versiones credenciales reales. APP_KEY debe inyectarse vía secret.

Activa cachés de Laravel en producción para mejorar el rendimiento. Usa config:cache, route:cache y view:cache. Consulta la documentación de Laravel para detalles.

  • scripts.test: vendor/bin/phpunit
  • scripts.analyse: vendor/bin/phpstan analyse
  • scripts.lint: vendor/bin/php-cs-fixer fix --dry-run --diff
  • scripts.post-deploy: php artisan optimize && php artisan migrate --force

Crea el workflow en GitHub Actions

Crea el archivo .github/workflows/ci.yml. Usa on: push y on: pull_request para validar nuevas modificaciones. Configura una matriz de versiones de PHP si es necesario.

Elige ubuntu-latest como runner e instala PHP con las extensiones necesarias. Usa caché del Composer apuntando a composer.lock. Esto reduce el tiempo de instalación.

Si tus pruebas requieren base de datos, usa los servicios del runner. Levanta MySQL o PostgreSQL como service y ejecuta migrations antes de las pruebas.

Separa jobs por objetivo. Por ejemplo: build y pruebas en un job; análisis estático en otro; deploy en un job condicionado por branch y aprobación del entorno.

Paso Objetivo Ejemplos de comandos
Setup PHP Definir versión y extensiones Instalar PHP 8.2/8.3, intl, mbstring, pdo, pdo_mysql/pdo_pgsql
Cache Composer Acelerar dependencias composer install --prefer-dist --no-interaction --no-progress
Provisionar DB Preparar pruebas Crear base de datos, php artisan key:generate, migrations
Pruebas Validar código vendor/bin/phpunit --colors=never
Análisis estático Detectar errores temprano vendor/bin/phpstan analyse
Lint Estandarizar estilo vendor/bin/php-cs-fixer fix --dry-run
Deploy Entregar con control php artisan down/up, migrate --force, optimize

Pruebas, calidad y cobertura

Ejecuta pruebas rápidas y fiables. Prioriza unitarias e integración con SQLite en memoria cuando sea posible. Esto reduce costes y fallos intermitentes.

Usa informes de cobertura cuando tenga sentido. La cobertura no garantiza calidad, pero ayuda a identificar áreas sin pruebas.

Adopta análisis estático con PHPStan o Psalm. Detectan errores de tipo y contractuales antes de llegar a producción.

Estandariza el estilo con PHP-CS-Fixer o PHPCS. Código consistente facilita revisiones y reduce conflictos.

  • Prueba el dominio sin acceder a la red innecesariamente.
  • Evita pruebas frágiles que dependan de fechas y timeouts.
  • Marca pruebas lentas y ejecútalas solo en pushes a main.
  • Los fallos deben bloquear el merge en pull requests.

Seguridad: secrets, permisos y aislamiento

Nunca versiones credenciales. Usa GitHub Actions secrets para APP_KEY, credenciales de base de datos, claves SSH y tokens de despliegue. Restringe acceso por entorno.

Aplica el principio de menor privilegio. Crea usuarios específicos para despliegue con permisos limitados. Evita claves reutilizadas.

Oculta salidas sensibles en los logs. Desactiva el eco de variables críticas. Revoca y rota credenciales periódicamente.

Considera OpenID Connect para autenticar en proveedores cloud sin claves persistentes. Esto reduce el riesgo de filtración.

  • Segrega staging y producción con secrets y entornos distintos.
  • Exige revisión o aprobación para promover a producción.
  • Audita quién puede ver y editar secrets en el repositorio.
  • Evita echo de variables sensibles en steps del workflow.

Despliegue continuo: staging y producción con seguridad

Crea entornos en GitHub (staging y production) con protección y aprobación. El despliegue solo inicia si los jobs de calidad han pasado.

Define la estrategia de empaquetado. Puedes generar un artefacto con vendor y assets ya compilados, o construir en el servidor. Los artefactos reducen variaciones.

En el despliegue, usa ventanas previsibles. En Laravel, ejecuta config:cache, route:cache y view:cache. Después, ejecuta migrations con --force.

Para zero‑downtime, emplea releases versionadas con symlink a current. Publica una nueva carpeta release, ejecuta migrations y apunta el symlink a ella.

¿Trabajas con queues? Reinicia los workers tras el despliegue. En Laravel Horizon, usa horizon:terminate para recargar código sin detener la cola.

  • Orden sugerida: poner el sitio en mantenimiento, publicar artefacto, ejecutar migrations, limpiar cachés específicos, salir de mantenimiento.
  • Haz rollback fácil manteniendo de 3 a 5 releases anteriores.
  • Automatiza verificación de salud tras el despliegue con una ruta de status.
  • Considera Docker para estandarizar el runtime, especialmente en equipos grandes.

Observabilidad, rollback y continuidad

Monitorea métricas y logs para confirmar el éxito del despliegue. Las alertas ayudan a actuar rápido cuando algo se degrada.

Implementa health checks y una prueba de humo automatizada tras el despliegue. Si falla, lanza rollback a la release anterior.

Mantén backups consistentes de la base de datos y de los archivos críticos antes de cambios sensibles. Esto reduce el impacto en incidentes.

  • Centraliza logs de aplicación y servidor.
  • Rastrea la versión del commit y número de release en headers.
  • Crea playbooks de rollback y pruébalos regularmente.
  • Integra alertas con el chat o correo del equipo.

Errores comunes y checklist final

Algunos problemas se repiten en pipelines nuevos. Mapearlos de antemano acelera la estabilización y evita incidentes innecesarios.

Usa esta checklist para validar los puntos esenciales antes de habilitar despliegue automático a producción.

  • Errores comunes: no versionar composer.lock; olvidar APP_KEY en el entorno; ejecutar migrations sin backup; dependencias del SO no instaladas; pipelines lentos por falta de caché.
  • Checklist: triggers definidos; matrix de PHP probada; caché del Composer activo; base de datos de pruebas provisionada; secrets configurados; entornos con aprobación; script de despliegue idempotente; rollback documentado.

Preguntas frecuentes

¿Cómo manejar la base de datos en despliegues automatizados?

Ejecuta migrations con --force solo después de que las pruebas hayan pasado y tras realizar backups. Prefiere migraciones compatibles con versiones previas para minimizar riesgo. Mantén scripts de rollback cuando sea posible y planifica ventanas de mantenimiento para operaciones que bloqueen tablas. En entornos críticos, prueba las migraciones en staging antes de promover a producción.

¿Necesito usar Docker para CI/CD en GitHub Actions?

No es obligatorio usar Docker en GitHub Actions. Docker facilita estandarizar el runtime y reproducir problemas de entorno, pero para proyectos pequeños los runners alojados con servicios de base de datos suelen ser suficientes. Evalúa Docker cuando el setup local o el servidor varíe entre desarrolladores o cuando necesites imágenes reproducibles para producción.

¿Cómo optimizar el tiempo del pipeline?

Reduce el tiempo del pipeline activando la caché de Composer vinculada a composer.lock, desactivando Xdebug en CI y usando prefer-dist al instalar dependencias. Aísla pruebas lentas y ejecútalas solo en pushes relevantes; ejecuta análisis estático en paralelo y evita compilar assets en pull requests que no modifiquen frontend. También aprovecha matrices y cachés por job.

¿Es seguro guardar APP_KEY en los secrets de GitHub?

Guardar APP_KEY en los secrets de GitHub es una opción recomendada si se controla el acceso por entorno y se audita quién puede ver o editar secrets. No muestres el valor en logs ni salidas. Rota las claves periódicamente y, cuando el proveedor lo permita, considera inyectar la variable directamente desde el PaaS para reducir exposición.

¿Cómo separar staging y producción en el workflow?

Crea entornos separados en GitHub (staging y production) con secrets distintos y políticas de protección que exijan aprobación para producción. Condiciona el job de despliegue al branch adecuado (por ejemplo main para producción y develop para staging) y usa artefactos separados por entorno si necesitas diferencias en paquetes o assets. Documenta el flujo de promoción entre entornos.

¿Puedo usar runners self-hosted para el despliegue?

Sí, los runners self-hosted permiten controlar dependencias, acceso a recursos privados y la red, pero requieren mantenimiento operativo y medidas de seguridad adicionales. Restringe permisos, aísla proyectos y mantén el sistema y las dependencias actualizados. Úsalos cuando necesites conectividad a recursos internos o control completo del entorno de ejecución.

¿Listo para configurar tu pipeline CI/CD?

¿Quieres acelerar la implementación de CI/CD con GitHub Actions en PHP/Laravel o revisar tu pipeline actual? Hablemos sobre tu contexto y los próximos pasos.

Hablar sobre mi pipeline

Ver también