Deploy Laravel y Vue a cPanel con GitHub Actions

En pocas palabras: Con GitHub Actions, cada git push compila el frontend Vue con Vite, instala dependencias con Composer y npm, y transfiere los archivos a cPanel por SSH, sin ZIP manual. El deploy es push-based: el servidor nunca guarda credenciales de GitHub, según una guía del 30 de julio de 2026.

Automatizar el deploy de Laravel y Vue a cPanel con GitHub Actions reemplaza un proceso manual lento por un simple push. Cada vez que subís código a tu rama, Actions compila el frontend, empaqueta el backend y lo copia por SSH al servidor. Cero ZIP a mano, cero File Manager.

GitHub Actions es la plataforma de integración y despliegue continuo de GitHub que ejecuta flujos de trabajo automáticos cuando ocurre un evento en el repositorio, como un push. Para desplegar Laravel y Vue en cPanel, un workflow instala dependencias con Composer y npm, compila los assets de Vite y transfiere los archivos al hosting compartido por SSH, sin subir archivos comprimidos manualmente.

¿Por qué automatizar el deploy de Laravel en lugar de subirlo a mano a cPanel?

Porque el deploy manual es lento y frágil. Corregís un bug, compilás el frontend de Vue, armás un ZIP, abrís el File Manager de cPanel, subís, extraés, corrés las migraciones, limpiás los cachés de Laravel y recién ahí revisás si la app sigue en pie. El cambio de código te llevó dos minutos. El deploy, mucho más.

Ponele que estás en un equipo de tres personas y cada uno sube ZIPs distintos. ¿Quién garantiza que todos corrieron las migraciones? Nadie. Ahí aparecen los “funciona en mi máquina”. Con un pipeline automático, el proceso es idéntico siempre: mismo build, mismos pasos, mismo resultado.

• Velocidad: un push dispara todo el flujo en segundos.
• Consistencia: el runner ejecuta exactamente los mismos comandos en cada deploy.
• Menos errores humanos: no te olvidás de php artisan migrate nunca más.
• Trazabilidad: cada deploy queda registrado con su commit en la pestaña Actions.

¿Qué diferencia hay entre deploy push-based y pull-based?

En un deploy push-based, GitHub Actions inicia la conexión y empuja los archivos al servidor por SSH. En pull-based, es el servidor de cPanel el que tira (pull) del repositorio. La diferencia parece menor, pero cambia todo el modelo de seguridad.

Acá viene lo bueno: con push-based, el servidor de cPanel no clona ni hace pull del repo privado. No necesita deploy key de GitHub, ni personal access token, ni SSH key a nivel cuenta. El único secreto en juego es una SSH key entre GitHub Actions y cPanel, y eso mantiene el setup más simple y evita guardar credenciales de tu repo en el server de producción, tal como describe la fuente original.

Aspecto	Push-based (GitHub Actions → cPanel)	Pull-based (cPanel tira del repo)
Quién inicia	GitHub Actions	El servidor de cPanel
Credenciales de GitHub en el server	No	Sí (deploy key o token)
Build de Vue/Vite	En el runner, gratis	En el server (necesita Node)
Dependencia de webhooks de cPanel	No	Habitual
Superficie de ataque en producción	Menor	Mayor

¿Qué requisitos necesitás en cPanel antes de empezar?

Necesitás acceso SSH habilitado en cPanel, PHP 8 o superior, Composer disponible en el servidor y un usuario con permisos para escribir en el directorio de la app. El build de Node corre en GitHub, así que tu hosting no precisa Node instalado.

• SSH activo: revisalo en la sección “SSH Access” del panel. Si tu hosting AR ya te da SSH (como los planes de donweb.com), buena parte del trabajo está resuelta.
• PHP 8+ y Composer: confirmá la versión con php -v por SSH.
• Ruta de la app: anotá el path absoluto, algo como /home/usuario/app.
• Node.js: solo hace falta en el runner de Actions, no en el server.

Probá la conexión antes de seguir. Un ssh usuario@tu-servidor -p 22 que te deje entrar es la señal verde. Si te pide contraseña y no entra con key, frená ahí: el problema es de permisos, no del workflow. Más contexto en nuestra comparativa de pipelines CI/CD 2026.

¿Cómo generar y configurar las SSH keys para GitHub Actions?

Generás un par de claves con ssh-keygen, pegás la pública en ~/.ssh/authorized_keys del cPanel y guardás la privada como secret en GitHub. El runner usa esa clave privada para autenticarse contra el servidor sin contraseña.

• Generá el par: ssh-keygen -t ed25519 -C "github-deploy" -f deploy_key.
• Copiá la pública al server: agregá el contenido de deploy_key.pub a ~/.ssh/authorized_keys en cPanel.
• Ajustá permisos: chmod 700 ~/.ssh y chmod 600 ~/.ssh/authorized_keys. Sin esto, el servidor ignora la key.
• Guardá la privada en GitHub: pegá el contenido de deploy_key como secret, por ejemplo DEPLOY_SSH_KEY.

¿Cómo se ve el archivo .github/workflows/deploy.yml?

El workflow define un disparador (push a una rama), instala dependencias, compila Vue y transfiere los archivos por SSH. Este es un ejemplo funcional que podés adaptar cambiando los secrets y las rutas.

name: Deploy a cPanel
on:
 push:
 branches: [ main ]
jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Setup PHP
 uses: shivammathur/setup-php@v2
 with: { php-version: '8.2' }
 - name: Composer install
 run: composer install --no-dev --optimize-autoloader
 - name: Setup Node
 uses: actions/setup-node@v4
 with: { node-version: '20' }
 - name: Build Vue/Vite
 run: |
 npm ci
 npm run build
 - name: Empaquetar (sin node_modules ni .env)
 run: tar --exclude='node_modules' --exclude='.env' -czf app.tar.gz .
 - name: Subir por SSH
 uses: appleboy/[email protected]
 with:
 host: ${ secrets.SERVER_IP }
 username: ${ secrets.SERVER_SSH_USER }
 key: ${ secrets.DEPLOY_SSH_KEY }
 source: app.tar.gz
 target: ${ secrets.SERVER_PATH }

Después de subir el paquete, un segundo paso con appleboy/ssh-action lo extrae, corre php artisan migrate --force y limpia cachés. Ese paso es el que suele fallar la primera vez, así que dejalo con logs visibles.

¿Dónde se guardan las credenciales secretas en GitHub?

Los secretos van en Settings > Secrets and variables > Actions, dentro de tu repositorio. Nunca en el código, nunca en el YAML, nunca commiteados. Los referenciás en el workflow con la sintaxis ${ secrets.NOMBRE }.

• SERVER_IP: la IP o dominio de tu cPanel.
• SERVER_SSH_USER: el usuario de cPanel.
• DEPLOY_SSH_KEY: la clave privada que generaste.
• SERVER_PATH: la ruta absoluta donde vive la app.

El .env de producción se queda en el servidor y no se toca. Por eso lo excluís del paquete: si lo subieras, pisarías tus credenciales reales de base de datos con las del repo (spoiler: eso rompe la app en producción).

¿Qué pasa paso a paso cuando hacés push?

Al hacer push a la rama configurada, GitHub Actions dispara el workflow y ejecuta la secuencia completa hasta dejar la app corriendo. Subís el código, el runner clona su propia copia, instala las dependencias de producción con Composer, corre npm ci y compila Vite, arma el paquete sin los archivos que no van, se conecta por SSH al cPanel, sube y extrae los archivos, corre las migraciones con --force y limpia la config, y todo eso pasa sin que vos toques el servidor una sola vez.

¿Y si algo falla en el medio? El deploy se corta y la app anterior sigue en pie hasta que el paso problemático termine. Por eso conviene extraer sobre un directorio temporal y hacer el switch al final, para minimizar el downtime.

¿Cómo deployar Vue 3 (Vite) junto a la API de Laravel?

Compilás Vue 3 con npm run build, lo que genera la carpeta dist/, y servís esos assets desde el directorio public de Laravel. El backend expone la API y el frontend consume esa API con la URL correcta configurada en VITE_API_URL. Tema relacionado: al comparar GitHub Actions con otras herramientas.

El tema es que la variable VITE_API_URL se congela en el momento del build, no en runtime. Si compilás apuntando a localhost, tu producción va a buscar la API en la máquina del usuario (sí, en serio). Definí la URL de producción como variable en el runner antes del npm run build y listo.

Errores comunes al configurar el deploy en cPanel

• Permisos mal en .ssh: si authorized_keys no está en 600 y .ssh en 700, el servidor rechaza la key en silencio. Es la causa número uno de “Permission denied”.
• Subir .env en el paquete: pisás la config de producción con la del repo. Excluilo siempre del tar.
• Olvidar el flag --force en las migraciones: php artisan migrate sin --force pide confirmación interactiva y el runner se cuelga esperando un input que nunca llega.
• Incluir node_modules en la transferencia: son cientos de megas inútiles. El build ya generó los assets finales, no necesitás las dependencias crudas en el server.

Preguntas Frecuentes

¿Se puede hacer CI/CD en cPanel sin SSH?

Sí, pero es más limitado. Sin SSH podés usar deploy por FTP con acciones como ftp-deploy, aunque perdés la capacidad de correr comandos remotos como migraciones o limpieza de caché. Para un stack Laravel completo, SSH es la opción recomendada porque te deja ejecutar php artisan en el servidor.

¿Cuál es la diferencia entre SSH y FTP para deploy automático?

SSH transfiere archivos cifrados y permite ejecutar comandos remotos (migraciones, cachés, permisos). FTP solo copia archivos y, en su forma clásica, no cifra la conexión. Para automatizar Laravel conviene SSH; FTP sirve para sitios estáticos o cuando el hosting no ofrece acceso a shell.

¿GitHub Actions es gratis para deployar en hosting compartido?

GitHub Actions incluye minutos gratuitos por mes en repositorios privados y uso ilimitado en los públicos. Un deploy de Laravel más Vue suele consumir pocos minutos por corrida, así que para un proyecto individual el costo real tiende a cero. Los planes pagos aparecen recién con volúmenes altos de builds.

¿Cómo hago rollback si un deploy sale mal?

La forma simple es revertir el commit en Git y hacer push de nuevo, lo que dispara un deploy con la versión anterior. Una estrategia más robusta guarda cada release en un directorio con timestamp y mantiene un symlink hacia la versión activa, de modo que el rollback sea cambiar ese enlace.

¿Necesito Node.js instalado en mi cPanel?

No. En el modelo push-based, el build de Vue y Vite corre en el runner de GitHub Actions y solo viajan los assets ya compilados. Tu hosting compartido únicamente sirve archivos estáticos y ejecuta PHP, así que no precisás Node en el servidor.

Conclusión

Automatizar el deploy de Laravel y Vue a cPanel con GitHub Actions saca de tu día la parte más aburrida y propensa a error: subir ZIPs a mano. El modelo push-based que describe la guía de dev.to de julio de 2026 mantiene el servidor limpio de credenciales de GitHub y deja el build pesado en el runner, gratis.

Si recién arrancás, hacé esto: confirmá que tenés SSH, generá el par de claves con los permisos correctos, guardá los cuatro secrets y probá el workflow con un push a una rama de staging antes de tocar producción. Una vez que anda, el deploy deja de ser un evento y pasa a ser rutina. Que es justo lo que querés.

Fuentes

• Deploy Laravel and Vue to cPanel Automatically with GitHub Actions – guía original en dev.to (30/07/2026)
• Auto Deploy for Laravel on cPanel Using GitHub Action – Stephen Jude
• Laravel/Lumen CI/CD con GitHub Actions en hosting compartido – Medium
• Automate your Laravel app deployment with GitHub Actions – dev.to
• Configurar deploy automático de GitHub a cPanel – documentación