Desplegar Laravel desde GitHub con Git y .cpanel.yml de cPanel

Esta guía explica el flujo manual de Git y .cpanel.yml de cPanel para una aplicación Laravel. Si quieres gestionar repositorios, scripts, versiones y webhooks desde el área de clientes, utiliza Deploy+.

El ejemplo de cPanel actualiza un clon de trabajo. No crea por sí solo releases aisladas ni garantiza que la web permanezca sin interrupciones durante una actualización.

Preparar el acceso y el proyecto

Activa SSH y prepara una clave dedicada de lectura para el repositorio privado. Verifica la huella de GitHub y evita reutilizar una identidad con acceso a otros proyectos.

Trabaja primero con un dominio y una base de datos de pruebas. El repositorio debe incluir el código y composer.lock, pero no contraseñas, .env de producción ni archivos subidos por usuarios.

En cPanel > Git Version Control > Create, introduce la URL SSH, una ruta privada como ~/repositories/laravel (sustituye ~ por el directorio de tu cuenta si el formulario requiere una ruta absoluta) y un nombre identificativo. Si utilizas un alias SSH para la clave, empléalo también en la URL del clon.

Comprueba la rama y el contenido antes de configurar el despliegue.

Definir las tareas

Crea .cpanel.yml en la raíz del repositorio. Para mantener juntas las comprobaciones y detener el proceso si falla un comando, llama a un script versionado:

---
deployment:
  tasks:
    - /bin/bash /home/usuario_cpanel/repositories/laravel/deploy/cpanel.sh

Un ejemplo de deploy/cpanel.sh sería:

#!/bin/bash
set -euo pipefail
cd /home/usuario_cpanel/repositories/laravel

PHP_BIN=/opt/alt/php83/usr/bin/php
COMPOSER_BIN=/opt/cpanel/composer/bin/composer

test -x "$PHP_BIN"
test -f "$COMPOSER_BIN"
test -f composer.lock
test -f .env

"$PHP_BIN" "$COMPOSER_BIN" install --no-dev --no-interaction --prefer-dist --optimize-autoloader
"$PHP_BIN" artisan config:cache
"$PHP_BIN" artisan view:cache
"$PHP_BIN" artisan route:cache

Sustituye el usuario y confirma las rutas de PHP y Composer en tu cuenta. PHP 8.3 es solo el valor del ejemplo: el intérprete de consola debe ser compatible con tu aplicación y con la versión que sirve la web. No uses composer update para resolver dependencias directamente en producción.

Prepara el .env privado, la base de datos y los directorios persistentes antes de ejecutar el script. Si migras una aplicación existente, conserva su APP_KEY. Configura APP_DEBUG=false. Añade la compilación de recursos que requiera el proyecto, o publícalos ya compilados desde un entorno compatible.

Las migraciones de base de datos necesitan su propio plan probado. No se incluyen automáticamente aquí: un fallo del código no deshace una migración ni recupera datos.

Publicar solo la carpeta public

Laravel debe exponerse por su carpeta public, no por la raíz del repositorio. Revisa la raíz documental del dominio y las rutas que permite el servidor.

Para un dominio adicional o subdominio, utiliza una ruta admitida por cPanel. Si el dominio principal requiere conservar public_html, prepara con soporte o con la herramienta de despliegue la publicación adecuada. No borres ni renombres toda esa carpeta sin revisar otras webs, archivos y servicios que dependan de ella.

Antes de cambiar la publicación, guarda una copia de la web y la base de datos y acuerda cómo recuperar el destino anterior. Prueba primero el proyecto en su ubicación de ensayo.

Actualizar y desplegar

En el repositorio de cPanel, abre Manage > Pull or Deploy:

1. Ejecuta Update from Remote para obtener el código.
2. Comprueba el commit y la rama.
3. Ejecuta Deploy HEAD Commit para las tareas de .cpanel.yml.
4. Revisa el registro hasta su finalización y prueba la web.

Actualizar desde el remoto y ejecutar las tareas son operaciones distintas. Si la web sirve directamente el clon, el primer paso ya puede cambiar archivos visibles aunque aún no hayas ejecutado el segundo.

La petición equivalente de despliegue local es:

/usr/local/cpanel/bin/uapi --output=jsonpretty VersionControlDeployment create \
  repository_root='/home/usuario_cpanel/repositories/laravel'

Un result.status igual a 1 confirma que cPanel ha aceptado la solicitud. Consulta la tarea y su log_path hasta conocer el resultado final; no lo interpretes como «la aplicación ya funciona».

Automatizar sin solapar tareas

Un push a GitHub no inicia por sí solo el pull de cPanel. Para automatizarlo necesitas un receptor o un proceso que lo programe. Deploy+ ofrece esa integración sin tener que construir el receptor.

Si mantienes uno propio, valida la firma del proveedor, el repositorio y la rama antes de poner trabajo en cola. Usa comandos y rutas definidos en tu configuración, y conserva un bloqueo hasta que termine realmente el despliegue. Bloquear solo la llamada que pone una tarea en cola no evita que dos tareas posteriores se solapen.

No publiques una URL que ejecute comandos al visitarla y no incorpores el contenido del webhook directamente a la shell. Registra entrega, commit y resultado sin secretos.

Validar y recuperar

Prueba portada, una ruta dinámica, autenticación, formularios y recursos. Revisa logs y procesos que deban cargar el código nuevo. Si el despliegue falla, identifica qué tareas llegaron a ejecutarse antes de repetirlo.

Recuperar un directorio o un commit anterior no revierte bases de datos, .env ni archivos compartidos. Para actualizaciones frecuentes que necesiten alternar versiones, considera Deploy+ o una estrategia de releases con una reversión probada.