Cómo desplegar Laravel en cPanel usando GitHub Actions y SSH (desde Linux)

Desplegar aplicaciones Laravel en hosting compartido como cPanel puede parecer complicado al principio.

A diferencia de una VPS tradicional, aquí no tenemos control total del sistema, pero aún así podemos crear un flujo de despliegue moderno usando GitHub, GitHub Actions y SSH.

En este artículo veremos cómo:

• instalar Laravel en un servidor con cPanel
• usar GitHub como repositorio
• configurar GitHub Actions para deploy automático
• conectarnos al servidor vía SSH
• ejecutar comandos Laravel desde consola
• trabajar desde una máquina Linux

Este flujo permite que cada push a GitHub despliegue automáticamente la aplicación.

1. Requisitos

Antes de empezar necesitas:

• Cuenta de GitHub
• Hosting con cPanel
• Acceso SSH habilitado
• Laravel instalado localmente
• Una máquina Linux (Mint, Ubuntu, etc.)

Herramientas necesarias en Linux:

• git
• ssh
• rsync
• node
• npm

2. Crear el proyecto Laravel

Si aún no tienes el proyecto:

composer create-project laravel/laravel proyecto

Entrar al proyecto:

cd proyecto

 

Probar que funciona:

php artisan serve

3. Crear el repositorio en GitHub

Inicializa git en tu proyecto:

git init
git add .
git commit -m "first commit"

Agrega el repositorio remoto:

git remote add origin https://github.com/USUARIO/REPO.git

Sube la rama principal:

git push -u origin main

 

Si usas entorno staging puedes crear otra rama:

git checkout -b develop
git push -u origin develop

4. Preparar el servidor cPanel

En cPanel crea un subdominio o dominio que apunte a una carpeta fuera de public_html.

Ejemplo:

/home/usuario/laravel-app

 

y el document root debe apuntar a:

/home/usuario/laravel-app/public

Esto es importante porque Laravel sirve todo desde la carpeta public.

5. Activar acceso SSH en cPanel

En cPanel busca:

SSH Access

y genera una clave.

Luego conecta desde Linux:

ssh usuario@servidor

 

Ejemplo:

ssh usuario@servidor.com

Si todo está bien verás algo como:

[usuario@server ~]$

6. Crear una clave SSH para GitHub Actions

En tu máquina Linux crea una clave:

ssh-keygen -t ed25519 -C "github-actions"

Se generarán dos archivos:

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

La clave pública debe agregarse al servidor.

En el servidor:

~/.ssh/authorized_keys

Agrega la clave pública.

7. Guardar secretos en GitHub

En tu repositorio entra a:

Settings > Secrets and variables >Actions

Agrega:

SSH_HOST
SSH_USER
SSH_PORT
SSH_PRIVATE_KEY

Ejemplo:

SSH_HOST=server.com
SSH_USER=usuario
SSH_PORT=22
SSH_PRIVATE_KEY=contenido de id_ed25519

8. Crear GitHub Actions para deploy

Crea el archivo:

.github/workflows/deploy.yml

Ejemplo básico usando rsync:

name: Deploy Laravel

on:
push:
branches: [main, develop]

jobs:
deploy:
runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20

- name: Build assets
run: |
npm install
npm run build

- name: Prepare SSH
run: |
mkdir -p ~/.ssh
echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_ci
chmod 600 ~/.ssh/id_ci
ssh-keyscan -p ${{ secrets.SSH_PORT }} ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts

- name: Deploy with rsync
run: |
rsync -az --delete \
-e "ssh -i ~/.ssh/id_ci -p ${{ secrets.SSH_PORT }}" \
--exclude ".git" \
--exclude "node_modules" \
--exclude ".env" \
./ \
${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/home/usuario/laravel-app/

 

Ahora cada push a GitHub desplegará automáticamente.

9. Instalar dependencias en el servidor

Una vez desplegado el código entra por SSH:

ssh usuario@server

Luego entra al proyecto:

cd /home/usuario/laravel-app

Instala dependencias:

composer install --no-dev --optimize-autoloader

10. Crear archivo .env

Laravel necesita un .env.

Puedes copiar el ejemplo:

cp .env.example .env

Editar:

nano .env

Configura:

APP_NAME
APP_URL
DB_DATABASE
DB_USERNAME
DB_PASSWORD

11. Generar la key de Laravel

php artisan key:generate

12. Ejecutar migraciones

Si tu servidor usa PHP de cPanel puede ser algo como:

ea-php82

 

Ejemplo:

ea-php82 artisan migrate

 

o

/opt/cpanel/ea-php82/root/usr/bin/php artisan migrate

13. Permisos necesarios

Laravel necesita permisos en:

storage
bootstrap/cache

Ejecuta:

chmod -R 775 storage
chmod -R 775 bootstrap/cache

14. Comandos útiles por SSH

Entrar al servidor:

ssh usuario@server

Entrar al proyecto:

cd /home/usuario/laravel-app

 

Limpiar caché:

php artisan optimize:clear

Migraciones:

php artisan migrate

15. Flujo final de trabajo

El flujo queda así:

1. Desarrollas en local
2. haces commit
3. haces push a GitHub

git add .
git commit -m "update"
git push

1. GitHub Actions se ejecuta
2. se conecta por SSH al servidor
3. sincroniza archivos
4. la app queda actualizada

Todo automáticamente.

Aunque cPanel no está pensado para despliegues modernos, con GitHub Actions + SSH + rsync podemos crear un flujo bastante profesional.

Ventajas de este sistema:

• deploy automático
• control de versiones
• staging y producción
• rollback fácil con git
• sin subir archivos manualmente por FT