# Cómo implementar un sitio desde Git

Source: https://support.kapsulehost.com/es-es/site-git-deploy

Git Deploy conecta un repositorio con un sitio para que cada envío a la rama elegida clone el código, ejecute su compilación y publique el resultado. Esta guía cubre la conexión inicial, los dos pasos del lado del repositorio que completan la configuración, la lectura del historial de despliegues y la detección del buildpack que decide cómo se compila una aplicación Node.js.

## Dónde Se Encuentra Git Deploy

Abra **Sitios web**, haga clic en el sitio, abra el grupo **Environment** en el menú izquierdo del sitio y elija **Despliegue con Git**. Hay dos páginas relacionadas cerca:

- **Despliegues**, el historial completo de despliegues de este sitio, en el mismo grupo **Environment**.
- **Buildpack**, la estrategia de compilación detectada, en sitios Node.js, en el grupo **Aplicaciones**.

La página de Git Deploy se describe a sí misma con claridad: conecte un repositorio y cada envío a la rama configurada activa una compilación y un despliegue.

![La página de Git Deploy para un sitio en KPanel, donde hay un repositorio conectado](https://support.kapsulehost.com/help/screenshots/site-git-deploy.4716f1a9.webp)

## Conectar un Repositorio

1. Elija su **Provider**: GitHub, GitLab o Bitbucket.
2. Introduzca la **URL del repositorio**. La forma SSH es la que quiere, por ejemplo `git@github.com:user/repo.git`.
3. Establezca la **Branch** desde la que desplegar. El campo comienza en `main`.
4. Opcionalmente, establezca un **Comando de compilación**, por ejemplo `npm run build`.
5. Opcionalmente, establezca un **Directorio de salida**, por ejemplo `dist`, `public`, o `.` para un repositorio que ya está compilado.
6. Haga clic en **Conectar repositorio**.

Deje el comando de compilación y el directorio de salida vacíos si su repositorio ya es desplegable tal cual, lo cual es el caso habitual para un sitio PHP sencillo o estático.

### Scripts Avanzados

Al expandir **Avanzado** aparecen dos campos adicionales:

- **Script pre-despliegue**, que se ejecuta antes de la compilación.
- **Script post-despliegue**, que se ejecuta después del despliegue.

Utilice el gancho post-despliegue para las tareas que deben ocurrir una vez que el código nuevo está en su lugar: vaciar una caché de la aplicación, ejecutar una migración de base de datos, reiniciar un worker.

### Despliegue Automático Al Hacer Push

El interruptor en la parte inferior de la tarjeta controla si los envíos despliegan o no. Cuando está activado, cada envío a la rama configurada activa un despliegue. Cuando está desactivado, los despliegues solo se ejecutan cuando usted los activa manualmente con **Desplegar ahora**.

> **Tip:** Desactive el despliegue automático durante una congelación de código o un incidente, en lugar de desconectar el repositorio. Desconectar descarta la clave de despliegue y el secreto del webhook, por lo que tendrá que rehacer ambos pasos del lado del repositorio después.

## Completar la Configuración En Su Repositorio

Conectar el repositorio en KPanel es solo el primero de tres pasos. Hasta que se haya ejecutado un despliegue, la página muestra un aviso que dice **Completar configuración: quedan 2 pasos** con todo lo que necesita.

### Paso 2: Añadir la Clave de Despliegue

KapsuleHost necesita acceso de lectura para clonar su repositorio. El aviso muestra una clave pública con un botón **Copiar clave**.

Péguela en las claves de despliegue de su repositorio. Para GitHub, el aviso ofrece un acceso directo **Añadir a GitHub** directamente a la página de configuración correspondiente. El acceso de lectura es suficiente; no conceda permisos de escritura.

### Paso 3: Añadir el Webhook

El webhook es lo que le indica a KapsuleHost que se ha producido un envío. El aviso le proporciona tres valores:

| Campo | Valor |
|---|---|
| URL de carga | Una URL que termina en `/api/git-deploy/webhook/` más el ID de este sitio |
| Secreto | Un secreto de firma generado, oculto hasta que haga clic en el icono del ojo |
| Tipo de contenido | `application/json` |

Copie cada uno en la configuración de webhooks de su repositorio. Para GitHub hay un acceso directo **Añadir webhook a GitHub**. Configure el tipo de contenido como JSON, no el predeterminado codificado como formulario, o la carga no se podrá interpretar.

> **Warning:** Trate el secreto del webhook como una contraseña. Cualquiera que lo tenga, junto con la URL de carga, puede activar un despliegue de su sitio. Ambos valores solo se muestran a las personas que ya pueden administrar el sitio, y el secreto permanece oculto detrás del icono del ojo hasta que lo solicite.

## Desplegar Manualmente

Haga clic en **Desplegar ahora** en la página de Git Deploy para compilar y desplegar el estado actual de la rama configurada sin enviar un commit. Esto funciona tanto si el despliegue automático está activado como si no, lo que lo convierte en la herramienta adecuada durante una congelación: los envíos se ignoran, pero aun así puede publicar la corrección.

## Leer el Historial de Despliegues

Abra **Environment** y luego **Despliegues**. La página se titula **Historial de despliegues** y enumera cada despliegue activado por webhook o manualmente, empezando por el más reciente.

Cada fila contiene:

- Un icono de estado y el SHA corto del commit, con la rama como una etiqueta.
- El mensaje del commit, o **Implementación manual** si no había ningún mensaje de commit que mostrar.
- El autor, hace cuánto se ejecutó, cuánto tardó y qué lo activó.
- Una etiqueta de estado.

Los estados son **pending**, **building**, **deploying**, **success** y **failed**. Mientras algo está en curso, la página se actualiza automáticamente cada cinco segundos y muestra una nota de **Actualización automática** debajo de la tabla, de modo que puede dejarla abierta y ver cómo se completa un despliegue.

### Cuando un Despliegue Falla

Una fila fallida tiene un botón **Error** a la derecha. Haga clic en él para expandir la salida de error capturada en línea, sin salir de la página. Esa salida es el propio texto de error de la compilación, por lo que generalmente nombra el archivo o el comando que falló.

Resuélvalo en este orden: lea el error, reproduzca el mismo comando de compilación localmente, corríjalo, envíe el cambio. Si la compilación funciona localmente pero no aquí, la diferencia casi siempre está en el entorno: una dependencia que falta y que está instalada globalmente en su máquina, o un archivo que está en su directorio de trabajo pero no se ha confirmado.

## Detección del Buildpack

En sitios Node.js, la página **Buildpack** del grupo **Aplicaciones** muestra cómo KapsuleHost ha decidido compilar su aplicación. La detección se ejecuta sobre los archivos en la raíz de su repositorio, y la primera coincidencia gana:

| Detectado | Activador |
|---|---|
| Buildpack personalizado | `kapsule.config.yaml` o `kapsule.config.yml` en la raíz |
| Buildpack de Dockerfile | `Dockerfile` en la raíz |
| Node.js | `package.json` con un script `start`, `build` o `dev` |
| Python | `requirements.txt` o `pyproject.toml` |
| PHP | `composer.json` |
| Estático | `index.html` en la raíz |

Si no hay coincidencias, la página lo indica y enumera los activadores admitidos. Añada un `Dockerfile` o un `kapsule.config.yaml` para tomar control explícito de la compilación.

### Ejecutar una Compilación

Haga clic en **Ejecutar compilación** para ponerla en cola. La página consulta cada tres segundos mientras una ejecución está en curso, y la tabla **Compilaciones recientes** muestra las últimas ejecuciones con su hora de inicio, tipo, estado, duración y referencia de la imagen resultante. Haga clic en una fila para ver el final de su registro.

Solo puede haber una compilación en curso a la vez. Activar una segunda mientras una está en cola o en ejecución se rechaza con **Una compilación ya está en progreso**, lo cual es intencionado: tener dos compilaciones escribiendo la misma salida a la vez es la forma de acabar con un sitio a medio desplegar.

## Desconectar

Haga clic en **Disconnect** y confirme. La confirmación es explícita sobre el alcance del cambio: la configuración de Git Deploy y la clave de despliegue se eliminan, y los archivos de su sitio no se ven afectados. El sitio sigue sirviendo lo último que se desplegó.

Ordene después eliminando la clave de despliegue y el webhook en la configuración de su repositorio. Simplemente dejarán de funcionar, pero dejar entradas obsoletas dificulta la próxima auditoría.

## Solución de Problemas

**Los envíos no activan nada.** Compruebe primero el interruptor de despliegue automático, luego el webhook en su repositorio. La mayoría de los proveedores muestran las entregas recientes y sus códigos de respuesta, lo que le indica de inmediato si la solicitud salió siquiera de su repositorio.

**La clonación falla.** La clave de despliegue falta, se pegó con un salto de línea incluido, o se añadió al repositorio equivocado. Cópiela de nuevo con el botón **Copiar clave** en lugar de seleccionar el texto manualmente.

**El despliegue se completa pero el sitio no cambia.** El directorio de salida probablemente es incorrecto. Si su compilación escribe en `dist` y el directorio de salida está vacío, los archivos compilados nunca llegan a la raíz servida.

**Todo dice pending y nunca avanza.** El despliegue se puso en cola pero nunca se recogió. Active un **Desplegar ahora** manual y revise la página de Deploys en busca de una fila de error.

## A Dónde Ir Después

- [Despliegues de Vista Previa Para Pull Requests](https://support.kapsulehost.com/es-es/site-preview) añade una URL por cada PR sobre esta configuración.
- [Almacenamiento de Secretos de Aplicación Para un Sitio](https://support.kapsulehost.com/es-es/site-secrets) para las credenciales que su compilación y tiempo de ejecución necesitan.
- [Registro de Actividad del Sitio](https://support.kapsulehost.com/es-es/site-activity-log) registra los cambios de configuración realizados aquí.