Automatizar el deploy en cPanel con el fichero .cpanel.yml

La interfaz de Git de cPanel no solo guarda tus repositorios: también puede poner en producción los cambios (hacer el deploy) ejecutando las tareas que tú definas en el fichero .cpanel.yml.

Si buscas un caso completo, paso a paso, mira deploy automático desde GitHub a cPanel con Laravel. Si prefieres no configurarlo a mano, Deploy+ lo hace desde el área de clientes.

El fichero .cpanel.yml

Es un fichero de texto en formato YAML con la lista de comandos que se ejecutan en cada deploy: copiar ficheros a la carpeta pública, instalar dependencias, limpiar cachés… cualquier cosa que puedas hacer con un comando o un script.

Créalo en la raíz del repositorio, con ese nombre exacto (con el punto delante) y haz commit de él. Su estructura es esta:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html/
    - /bin/cp index.html $DEPLOYPATH
    - /bin/cp style.css $DEPLOYPATH

• Las tres primeras líneas son fijas: ---, deployment: y, debajo, tasks:.
• Cada tarea es una línea que empieza por - (guion y espacio), con la misma sangría.
• export DEPLOYPATH=... guarda la carpeta de destino en una variable, para no repetirla en cada línea.
• Los /bin/cp copian index.html y style.css del repositorio a la carpeta pública. Así la web se actualiza con los cambios.

Cambia usuario por tu usuario de cPanel. cp sobrescribe los ficheros que ya existan con ese nombre en el destino.

Copiar toda la web con rsync

Para no ir fichero a fichero, copia todo el contenido del repositorio excepto lo que no debe publicarse:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html/
    - /bin/rsync -a --exclude='.git' --exclude='.cpanel.yml' ./ $DEPLOYPATH

rsync no borra del destino los ficheros que ya no estén en el repositorio. Puedes añadir --delete para que lo haga, pero solo si esa carpeta contiene únicamente lo que viene del repositorio: borraría también imágenes subidas, cachés o el .htaccess si no están en él.

Tareas de una aplicación PHP

Puedes ejecutar cualquier herramienta con su ruta completa. Por ejemplo, instalar dependencias con Composer y vaciar la caché de una aplicación Laravel:

---
deployment:
  tasks:
    - cd /home/usuario/repositories/proyecto && /usr/local/bin/php /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader
    - cd /home/usuario/repositories/proyecto && /usr/local/bin/php artisan config:cache

Usa siempre rutas absolutas: las tareas no cargan tu configuración de terminal. Si no sabes dónde está un programa, ejecuta which php (o el que sea) por SSH.

Si las tareas son muchas o dependen unas de otras, ponlas en un script del repositorio y llama solo a ese script desde .cpanel.yml:

---
deployment:
  tasks:
    - /bin/bash /home/usuario/repositories/proyecto/deploy.sh

Empieza el script con set -e para que se detenga en el primer comando que falle.

Cuándo se ejecuta el deploy

Push deployment: haces push al repositorio de cPanel

Si tu repositorio local tiene como remoto el repositorio de cPanel, al hacer git push cPanel ejecuta automáticamente las tareas de .cpanel.yml. Para que lo haga, el repositorio de cPanel tiene que tener una rama activa y no tener cambios sin confirmar.

Para añadir el repositorio de cPanel como remoto, copia la Clone URL que aparece en Git™ Version Control > Manage y ejecuta en tu equipo:

git remote add cpanel ssh://usuario@tudominio.com/home/usuario/repositories/proyecto
git push cpanel main

Pull deployment: el código está en GitHub, GitLab u otro remoto

Si el repositorio de cPanel es un clon de uno de GitHub, haz push a GitHub como siempre y, después, en Git™ Version Control > Manage > Pull or Deploy:

1. Update from Remote descarga los cambios.
2. Deploy HEAD Commit ejecuta las tareas de .cpanel.yml.

Un push a GitHub no avisa por sí solo a cPanel. Para que se despliegue automáticamente en cada push, usa un webhook de GitHub como se explica en el caso práctico con GitHub, o una tarea cron como la del siguiente apartado.

Lanzar el deploy con la API o una tarea cron

Por SSH, este comando hace lo mismo que el botón Deploy HEAD Commit:

/usr/local/cpanel/bin/uapi VersionControlDeployment create repository_root=/home/usuario/repositories/proyecto

Cambia la ruta por la de tu repositorio. Si la respuesta incluye status: 1, cPanel ha puesto el deploy en marcha; el resultado de cada tarea queda en el fichero de log_path.

Para desplegar cada cierto tiempo lo que haya en GitHub, crea una tarea cron que primero descargue los cambios y luego despliegue:

cd /home/usuario/repositories/proyecto && /usr/bin/flock -n /home/usuario/.deploy.lock sh -c 'git pull -q && /usr/local/cpanel/bin/uapi VersionControlDeployment create repository_root=/home/usuario/repositories/proyecto' >/dev/null

flock -n evita que se lancen dos a la vez si una ejecución tarda más de lo previsto. No pongas una frecuencia muy alta: cada 10 o 15 minutos suele bastar. Si solo quieres desplegar cuando haya cambios, el webhook es mejor opción.

Ver qué ha pasado en un deploy

Cada deploy deja un registro en ~/.cpanel/logs/ con el nombre vc_NUMERO_git_deploy.log. Ahí aparece cada comando, su salida y su código de salida: Task completed with exit code 0 es que ha ido bien; cualquier otro número indica el comando que ha fallado.

ls -t ~/.cpanel/logs/*git_deploy.log | head -1 | xargs cat

Si un deploy no se ejecuta al hacer push, revisa en Git™ Version Control > Manage que el repositorio tiene una rama activa y que .cpanel.yml está en la raíz y confirmado con commit.