Sitios web
Implementar un Sitio Desde Git
Git Deploy connects a repository to a site so that every push to your chosen branch clones the code, runs your build, and publishes the result. This guide covers the initial connection, the two…
Dónde se encuentra Git Deploy
Abre Websites, haz clic en el sitio, abre el menú Advanced en la barra de pestañas del sitio y elige Git Deploy. Dos páginas relacionadas se encuentran en el mismo menú:
- Deploys, el historial completo de implementación de este sitio.
- Buildpack, la estrategia de compilación detectada, en sitios Node.js.
La página Git Deploy se describe claramente: conecta un repositorio y cada push a tu rama configurada dispara una compilación e implementación.
Conectar un repositorio
- Elige tu Provider: GitHub, GitLab o Bitbucket.
- Introduce la Repository URL. La forma SSH es la que quieres, por ejemplo
git@github.com:user/repo.git. - Establece la Branch desde la que implementar. El campo comienza en
main. - Opcionalmente establece un Build command, por ejemplo
npm run build. - Opcionalmente establece un Output directory, por ejemplo
dist,public, o.para un repositorio que ya está compilado. - Haz clic en Connect repo.
Deja el comando de compilación y el directorio de salida vacíos si tu repositorio ya es implementable tal como está, que es el caso común para un sitio PHP simple o estático.
Advanced Scripts
Expandir Advanced revela dos campos adicionales:
- Pre-deploy script, que se ejecuta antes de la compilación.
- Post-deploy script, que se ejecuta después de la implementación.
Usa el gancho post-deploy para las cosas que deben ocurrir una vez que el código nuevo está en su lugar: limpiar una caché de aplicación, ejecutar una migración de base de datos, reiniciar un worker.
Auto-Deploy On Push
El interruptor en la parte inferior de la tarjeta controla si los pushes implementan en absoluto. Cuando está activado, cada push a la rama configurada dispara una implementación. Cuando está desactivado, las implementaciones solo se ejecutan cuando las activas manualmente con Deploy now.
Desactiva la implementación automática durante una congelación de código o un incidente en lugar de desconectar el repositorio. Desconectar descarta la clave de implementación y el secreto del webhook, así que tienes que rehacer ambos pasos del lado del repositorio después.
Finalizar la configuración en tu repositorio
Conectar el repositorio en KPanel es solo el primero de tres pasos. Hasta que se ejecute una implementación, la página muestra un banner que dice Complete setup: 2 steps remaining con todo lo que necesitas.
Paso 2: Agregar la clave de implementación
Kapsule necesita acceso de lectura para clonar tu repositorio. El banner muestra una clave pública con un botón Copy key.
Pégala en las claves de implementación de tu repositorio. Para GitHub, el banner ofrece un atajo Add to GitHub directo a la página de configuración correcta. El acceso de lectura es suficiente; no concedas acceso de escritura.
Paso 3: Agregar el Webhook
El webhook es lo que le dice a Kapsule que ha ocurrido un push. El banner te da tres valores:
| Campo | Valor |
|---|---|
| Payload URL | Una URL que termina en /api/git-deploy/webhook/ más el ID de este sitio |
| Secret | Un secreto de firma generado, oculto hasta que hagas clic en el icono del ojo |
| Content Type | application/json |
Copia cada uno en la configuración del webhook de tu repositorio. Para GitHub hay un atajo Add webhook to GitHub. Establece el tipo de contenido en JSON, no en el default codificado en formulario, o la carga útil no se procesará.
Trata el secreto del webhook como una contraseña. Cualquiera que lo tenga, más la URL de carga útil, puede disparar una implementación de tu 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 pidas.
Implementar manualmente
Haz clic en Deploy now en la página Git Deploy para compilar e implementar el HEAD actual de la rama configurada sin empujar una confirmación. Esto funciona tanto si la implementación automática está activada como si no, que es lo que la convierte en la herramienta correcta durante una congelación: los pushes se ignoran, pero aún puedes entregar la corrección.
Leer el historial de implementación
Abre Advanced y luego Deploys. La página se titula Deploy history y enumera cada implementación disparada por webhook o manualmente, la más nueva primero.
Cada fila contiene:
- Un icono de estado y el SHA de confirmación corto, con la rama como una etiqueta.
- El mensaje de confirmación, o Manual deploy si no hay mensaje de confirmación para mostrar.
- El autor, cuánto tiempo hace que se ejecutó, cuánto tiempo tardó y qué lo disparó.
- Una etiqueta de estado.
Los estados son pending, building, deploying, success y failed. Mientras algo está en vuelo, la página se actualiza cada cinco segundos y muestra una nota Refreshing automatically debajo de la tabla, así que puedes dejarla abierta y ver cómo se despliega una implementación.
Cuando falla una implementación
Una fila fallida obtiene un botón Error a la derecha. Haz clic en él para expandir la salida de error capturada en línea, sin salir de la página. Esa salida es el texto de error de la compilación en sí, así que generalmente nombra el archivo o el comando que falló.
Trabaja a través de él en este orden: lee el error, reproduce el mismo comando de compilación localmente, corrige, empuja. Si la compilación funciona localmente pero no aquí, la diferencia es casi siempre un ambiente, una dependencia faltante que se instala globalmente en tu máquina, o un archivo que está en tu directorio de trabajo pero no confirmado.
Detección de Buildpack
En sitios Node.js, la página Buildpack en el menú Advanced muestra cómo Kapsule ha decidido compilar tu aplicación. La detección se ejecuta sobre los archivos en la raíz de tu repositorio, y el primer coincidente gana:
| Detectado | Disparador |
|---|---|
| Custom buildpack | kapsule.config.yaml o kapsule.config.yml en la raíz |
| Dockerfile buildpack | 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 |
| Static | index.html en la raíz |
Si nada coincide, la página lo dice y enumera los disparadores admitidos. Agrega un Dockerfile o un kapsule.config.yaml para tomar el control de la compilación explícitamente.
Ejecutar una compilación
Haz clic en Run build para poner en cola una. La página sondea cada tres segundos mientras una compilación está en vuelo, y la tabla Recent builds muestra las últimas compilaciones con su hora de inicio, tipo, estado, duración y referencia de imagen resultante. Haz clic en una fila para ver su cola de registros.
Solo una compilación puede estar en vuelo a la vez. Disparar una segunda mientras una está en cola o en ejecución se rechaza con A build is already in progress, que es deliberado: dos compilaciones escribiendo la misma salida a la vez es cómo obtienes un sitio medio implementado.
Desconectar
Haz clic en Disconnect y confirma. La confirmación es explícita sobre el radio de alcance: se eliminan la configuración de implementación de Git y la clave de implementación, y tus archivos del sitio no se ven afectados. El sitio sigue sirviendo lo que se implementó por última vez.
Limpia después eliminando la clave de implementación y el webhook en la configuración de tu repositorio. Simplemente dejarán de funcionar, pero dejar entradas muertas dificulta la siguiente auditoría.
Solución de problemas
Los pushes no disparan nada. Primero comprueba el interruptor de implementación automática, luego el webhook en tu repositorio. La mayoría de proveedores muestran entregas recientes y sus códigos de respuesta, lo que te dice inmediatamente si la solicitud salió de tu repositorio en absoluto.
La clonación falla. La clave de implementación falta, se pegó con un salto de línea, o se agregó al repositorio incorrecto. Cópiala de nuevo con el botón Copy key en lugar de seleccionar el texto a mano.
La implementación tiene éxito pero el sitio no cambia. El directorio de salida es probablemente incorrecto. Si tu compilación se escribe a 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. La implementación fue puesta en cola pero nunca fue recogida. Dispara manualmente Deploy now y comprueba la página Deploys para una fila de error.
Hacia dónde ir después
- Preview Deploys For Pull Requests agrega una URL por RP además de esta configuración.
- Storing App Secrets For a Site para las credenciales que tu compilación y runtime necesitan.
- Site Activity Log registra cambios de configuración realizados aquí.