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.
Conectar un Repositorio
- Elija su Provider: GitHub, GitLab o Bitbucket.
- Introduzca la URL del repositorio. La forma SSH es la que quiere, por ejemplo
git@github.com:user/repo.git. - Establezca la Branch desde la que desplegar. El campo comienza en
main. - Opcionalmente, establezca un Comando de compilación, por ejemplo
npm run build. - Opcionalmente, establezca un Directorio de salida, por ejemplo
dist,public, o.para un repositorio que ya está compilado. - 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.
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.
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 añade una URL por cada PR sobre esta configuración.
- Almacenamiento de Secretos de Aplicación Para un Sitio para las credenciales que su compilación y tiempo de ejecución necesitan.
- Registro de Actividad del Sitio registra los cambios de configuración realizados aquí.