Cómo Hacer Deploy Automático con Git desde GitHub a cPanel: Guía Paso a Paso

Subir archivos por FTP cada vez que haces un cambio en tu código no es un workflow profesional. Es lento, propenso a errores y difícil de rastrear. La alternativa moderna: conectar tu repositorio Git con tu hosting para que cada push a la rama principal despliegue automáticamente los cambios en producción.

Si tienes hosting con cPanel (versión 78 o superior), tienes una herramienta nativa para hacer exactamente esto, sin necesidad de SSH ni plataformas externas. En esta guía vas a aprender dos métodos para configurar deploy automático, con ejemplos reales de archivos de configuración.

¿Qué es el deploy con Git en cPanel?

Git Version Control — la herramienta nativa de cPanel

Desde cPanel 78, existe la sección Git Version Control que te permite clonar repositorios, gestionar ramas y ejecutar deploys directamente desde la interfaz de cPanel. No es necesario instalar Git en tu servidor ni configurar nada adicional: la herramienta está lista para usar.

Por qué esto cambia el workflow de desarrollo

Sin Git deploy, tu workflow probablemente se ve así:

• Desarrollas en local
• Abres FileZilla o el administrador de archivos
• Subes los archivos cambiados uno por uno
• Esperas a que se complete la transferencia
• Verificas manualmente que todo funciona
• Si algo falla, vuelves a subir la versión anterior

Con Git deploy, el workflow es:

• Desarrollas en local
• Haces git push origin main
• Los cambios se despliegan automáticamente en producción
• En caso de problema, haces git revert y se revierte automáticamente

No solo es más rápido: es más seguro porque siempre tienes un registro de qué se deployó, cuándo y por qué.

Requisitos previos

Hosting con cPanel versión 78+ (con Git Version Control)

La mayoría de los hosting con cPanel actualizados incluyen Git Version Control. Para verificar si tu hosting lo tiene, inicia sesión en cPanel y busca el ícono de "Git Version Control" en la sección Files. Si no lo ves, es posible que tu hosting lo haya desactivado o que necesites una versión más reciente de cPanel.

Elevocloud incluye Git Version Control en todos sus planes con cPanel.

Repositorio en GitHub (o GitLab/Bitbucket)

Necesitas un repositorio Git remoto. GitHub es el más común, pero el proceso funciona igual con GitLab o Bitbucket. El repositorio puede ser público o privado.

Si aún no tienes tu código en Git, inicializa un repositorio:

cd /tu/proyecto
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/tuusuario/tu-repo.git
git push -u origin main

Acceso SSH (opcional pero recomendado)

SSH no es obligatorio para el deploy básico con Git Version Control de cPanel, pero sí lo es para el método de GitHub Actions. Si necesitas configurar acceso SSH, nuestra guía de acceso SSH en cPanel con comandos básicos te muestra cómo hacerlo.

Método 1 — Deploy con cPanel Git Version Control (sin SSH)

Este método usa la herramienta nativa de cPanel y no requiere acceso SSH ni línea de comandos. Ideal para empezar.

Paso 1: Crear repositorio en cPanel > Git Version Control

1. Ve a cPanel > Git Version Control
2. Haz clic en Create (Crear)
3. Completa los campos:
   • Repository Name: Un nombre descriptivo, por ejemplo mi-sitio-wordpress
   • Repository Path: La ruta en tu servidor, por defecto /home/usuario/mi-sitio-wordpress
   • Repository URL: La URL de tu repositorio en GitHub, por ejemplo https://github.com/tuusuario/tu-repo.git
4. Marca Clone Remote Repository para clonar desde GitHub
5. Haz clic en Create

cPanel clonará el repositorio y mostrará el estado de las ramas y commits.

Paso 2: Clonar desde URL de GitHub

Si tu repositorio es privado, cPanel te pedirá las credenciales de GitHub. Puedes usar un Personal Access Token (PAT) de GitHub en lugar de tu contraseña para mayor seguridad:

1. En GitHub, ve a Settings > Developer settings > Personal access tokens
2. Genera un token con permisos repo
3. Usa el token como contraseña cuando cPanel lo solicite

Una vez clonado, cPanel mostrará la rama activa (usualmente main), el último commit y el estado del deploy.

Paso 3: Configurar el archivo .cpanel.yml

El archivo .cpanel.yml es el corazón del deploy automático. Le dice a cPanel qué hacer cuando se detectan cambios en el repositorio.

Crea este archivo en la raíz de tu repositorio local y súbelo a GitHub:

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

Este ejemplo copia carpetas y archivos específicos desde el repositorio al directorio de despliegue. Ajusta las rutas y archivos según tu proyecto.

Estructura del .cpanel.yml: tasks y deployment

El archivo tiene dos secciones principales:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html
    - /bin/cp -R * $DEPLOYPATH

• deployment: Sección principal que define las operaciones de deploy
• tasks: Lista de comandos que se ejecutan en orden durante el deploy
• DEPLOYPATH: Variable que define el destino (generalmente public_html)

Los comandos se ejecutan en orden y son comandos de shell estándar de Linux. Puedes usar cp, mv, rm, mkdir y otros.

Nota importante: Los comandos se ejecutan con las rutas del repositorio clonado como directorio de trabajo. El repositorio clonado está en /home/usuario/nombre-repo/, no en public_html.

Paso 4: Deploy manual desde el panel

Después de configurar .cpanel.yml:

1. Haz push de cambios a tu repositorio en GitHub
2. Ve a cPanel > Git Version Control
3. Haz clic en Manage junto a tu repositorio
4. En la sección Pull or Deploy, haz clic en Update from Remote para traer los cambios nuevos
5. Luego haz clic en Deploy HEAD Commit para ejecutar el deploy

cPanel ejecutará los comandos del .cpanel.yml y mostrará el resultado.

Para que el deploy sea automático (sin necesidad de hacer clic en "Deploy"), necesitas configurar un webhook, lo cual explicamos más adelante.

Método 2 — Deploy automático con GitHub Actions

Si necesitas más control sobre el proceso de deploy — por ejemplo, ejecutar npm install, compilar assets, o correr tests antes de deployar — GitHub Actions es la alternativa más flexible.

Crear el archivo .github/workflows/deploy.yml

En tu repositorio local, crea el archivo .github/workflows/deploy.yml:

name: Deploy to cPanel

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install dependencies
        run: npm install

      - name: Build assets
        run: npm run build

      - name: Deploy via SSH
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          port: ${{ secrets.PORT }}
          source: "dist/*"
          target: "/home/usuario/public_html/"

Configurar FTP/SSH secrets en GitHub

En tu repositorio de GitHub, ve a Settings > Secrets and variables > Actions y agrega:

• HOST: La IP o dominio de tu servidor
• USERNAME: Tu usuario de cPanel
• SSH_KEY: Tu clave SSH privada para acceder al servidor
• PORT: El puerto SSH (generalmente 22 o uno personalizado)

Nunca pongas credenciales directamente en el archivo YAML. Los secrets de GitHub las mantienen seguras.

Disparar deploy en cada push a main

Con esta configuración, cada vez que haces git push origin main, GitHub Actions ejecuta automáticamente el workflow: instala dependencias, compila los assets y los sube al servidor por SSH.

Puedes ver el progreso en la pestaña Actions de tu repositorio en GitHub.

Ejemplo práctico: deploying un tema WordPress desde GitHub

Vamos a configurar el deploy de un tema WordPress personalizado desde GitHub a wp-content/themes/mi-tema/.

Estructura del repositorio

mi-tema-wordpress/
├── .cpanel.yml
├── style.css
├── functions.php
├── header.php
├── footer.php
├── index.php
├── single.php
├── page.php
├── assets/
│   ├── css/
│   ├── js/
│   └── images/
└── template-parts/

El .cpanel.yml para un tema WordPress

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html/wp-content/themes/mi-tema
    - /bin/cp style.css $DEPLOYPATH
    - /bin/cp functions.php $DEPLOYPATH
    - /bin/cp header.php $DEPLOYPATH
    - /bin/cp footer.php $DEPLOYPATH
    - /bin/cp index.php $DEPLOYPATH
    - /bin/cp single.php $DEPLOYPATH
    - /bin/cp page.php $DEPLOYPATH
    - /bin/cp -R assets $DEPLOYPATH
    - /bin/cp -R template-parts $DEPLOYPATH

Este .cpanel.yml copia cada archivo y carpeta del tema al directorio de WordPress. Cada vez que haces push de cambios al repositorio, cPanel los despliega automáticamente.

Para proyectos más complejos, puedes usar un workflow dev → staging → producción con ramas separadas en Git que deployan a diferentes ubicaciones.

Errores comunes y cómo solucionarlos

'Repository already exists' al clonar

Si intentas clonar un repositorio y cPanel muestra "Repository already exists", significa que ya hay un repositorio Git en esa ruta. Soluciones:

• Usa una ruta diferente para el nuevo repositorio
• Elimina el repositorio existente desde cPanel > Git Version Control > Manage > Delete
• Verifica que no haya una carpeta .git oculta en el destino

Permisos de archivos después del deploy

Después de un deploy, los archivos pueden tener permisos incorrectos (por ejemplo, 644 en vez de 755 para directorios). Para corregirlo:

find /home/usuario/public_html -type d -exec chmod 755 {} \;
find /home/usuario/public_html -type f -exec chmod 644 {} \;

Puedes ejecutar estos comandos por SSH o agregarlos al final de tu .cpanel.yml:

    - /bin/chmod 755 $DEPLOYPATH
    - /bin/chmod -R 755 $DEPLOYPATH/assets

Deploy no se dispara después del push

Si haces push a GitHub pero cPanel no detecta los cambios:

1. Verifica que .cpanel.yml existe en la rama que estás pusheando (generalmente main)
2. En cPanel > Git Version Control, haz clic en Update from Remote manualmente
3. Revisa que el webhook esté configurado correctamente (si usas deploy automático)
4. Verifica los logs de deploy en cPanel para mensajes de error

Si usas deploy manual (sin webhook), necesitas hacer clic en Update from Remote y luego Deploy HEAD Commit después de cada push.

Flujo de trabajo recomendado (dev → staging → producción)

Para proyectos serios, un flujo de trabajo con tres ambientes es lo ideal:

1. Dev (desarrollo): Tu máquina local donde escribes código
2. Staging (pruebas): Un subdominio como staging.tusitio.com donde pruebas cambios antes de publicarlos
3. Producción: El sitio público en tusitio.com

Configura dos repositorios en cPanel: uno que deploya a public_html/staging/ y otro a public_html/. Usa ramas de Git para controlar el flujo:

• Rama develop → deploy automático a staging
• Rama main → deploy manual a producción después de verificar en staging

Para más detalles sobre configurar ambientes de pruebas, consulta nuestra guía de ambiente staging en hosting.

Y si usas WP-CLI para gestionar WordPress, puedes agregar comandos WP-CLI a tu .cpanel.yml para automatizar tareas como flush de caché o actualización de base de datos después de cada deploy.

Hosting cPanel con Git Version Control activado — Elevocloud. Todos nuestros planes incluyen cPanel con Git Version Control listo para configurar tu deploy automático. Además, ofrecemos hosting optimizado para desarrolladores con acceso SSH, soporte para Node.js y herramientas de desarrollo modernas.