Orbit
Activar implementaciones mediante Deploy Hooks
A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a…
Un deploy hook es una URL secreta que pone en cola una nueva implementación cuando algo le envía una solicitud HTTP POST. No hay encabezado de autenticación: el secreto de la URL es la autenticación. Utiliza hooks para permitir que un CMS headless, una tarea cron, una pipeline de CI o cualquier otro webhook reconstruya tu proyecto sin necesidad de un git push.
Dónde Encontrar Deploy Hooks
Los hooks tienen su propia pestaña: abre tu proyecto en Orbit y haz clic en Hooks, en /orbit/<project-id>/hooks.
El mismo panel Deploy hooks también aparece a mitad de camino en la pestaña Settings del proyecto, para que puedas gestionarlos desde cualquiera de los dos lugares.
Crear un Deploy Hook
- Abre Orbit, luego tu proyecto, luego Hooks.
- Haz clic en Add deploy hook.
- Introduce un Hook name que tenga sentido dentro de seis meses. El marcador de posición sugiere la forma: "Contentful publish", "Nightly cron".
- Elige un Target environment. Por defecto es Production (default). Si tu proyecto tiene un ambiente de staging, puedes apuntar el hook a staging en su lugar.
- Haz clic en Create hook.
El hook aparece en la lista con su URL, un botón Copy URL y un botón Delete hook.
La URL del Hook
Las URLs de los hooks se ven así:
https://kpanel.kapsulehost.com/api/orbit/hooks/<token>
El token es un secreto único generado cuando creas el hook.
Trata una URL de hook exactamente como una clave API. Cualquiera que la tenga puede activar una implementación de tu proyecto, y ninguna de las compuertas de implementación de Orbit los detendrá: los bloqueos de implementación, la aprobación requerida, las verificaciones de CI requeridas y el éxito de staging requerido se aplican únicamente a las implementaciones activadas por push, y un hook pasa directamente. Nunca pegues una URL de hook en un repositorio público, un documento compartido, una captura de pantalla o un ticket de soporte.
Activar un Hook
Envía una solicitud POST. No se requieren cuerpo ni encabezados.
curl -X POST \
https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>
Orbit responde con HTTP 202 y el ID de implementación. La implementación aparece en la pestaña Deployments dentro de unos segundos.
El endpoint solo acepta POST. Una solicitud GET no activará una implementación. Algunas integraciones de webhook más antiguas tienen GET por defecto, así que comprueba el método si un hook que has configurado nunca se dispara.
Qué Despliega Realmente un Hook
El hook resuelve su ambiente objetivo (el que elegiste, o el ambiente de producción del proyecto), lee la rama de ese ambiente, y le pide al proveedor de git el commit head actual de esa rama. Luego pone en cola una implementación de ese commit.
Eso tiene tres consecuencias que vale la pena conocer:
- Un hook siempre despliega el branch head. No puedes pasar un SHA de commit o un nombre de rama en el cuerpo de la solicitud; el cuerpo de la solicitud se ignora completamente.
- Un hook necesita una conexión de proveedor funcional. Si has desconectado GitHub, GitLab o Bitbucket, el hook no puede leer el branch head y falla con un error en lugar de desplegar código obsoleto.
- Un hook reejcuta la compilación completa. No es una reversión y no es una promoción; es una compilación nueva de lo que esté actualmente en la rama.
Llamadas Repetidas y Superpuestas
Orbit maneja ráfagas de llamadas de hook de manera sensata en lugar de poner en cola una compilación para cada una.
- Si una implementación para el mismo commit ya está en vuelo en ese ambiente, el hook devuelve la implementación existente y marca la respuesta como deduplicada. No se inicia una segunda compilación.
- Si una compilación se está ejecutando para un commit diferente en ese ambiente, se cancela automáticamente y se reemplaza por la nueva, para que no pagues por una compilación cuya salida ya está supercedida.
Esto hace que los hooks sean seguros para un CMS que dispara un webhook por entrada publicada. Publicar seis páginas en un minuto produce una compilación, no seis, y no quema seis compilaciones de minutos.
Conectar un CMS Headless
La mayoría de los CMS headless tienen una función "webhook al publicar". El patrón siempre es el mismo: apunta el webhook a tu URL de hook, usa POST y deja los ajustes de autenticación vacíos.
Contentful
- Ve a Settings, luego Webhooks, luego Add webhook.
- Establece la URL en tu URL de hook de Orbit.
- Establece el método en POST.
- Establece el disparador en Publish, o en cualquier evento de contenido que deba reconstruir el sitio.
- Guarda.
Sanity
En el dashboard de tu proyecto, ve a API, luego Webhooks, luego Create webhook. Establece la URL en tu URL de hook, el método en POST, y elige el dataset y los eventos disparadores.
Prismic
En el dashboard, ve a Settings, luego Webhooks, y añade tu URL de hook. Prismic la llama en cada publicación de documento.
Conectar una Tarea Cron o una Pipeline de CI
Cualquier planificador que pueda hacer una solicitud HTTP funcionará:
# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>
Para CI, un deploy hook es la opción más simple cuando quieres que tu pipeline decida si ocurre una implementación. Es el enfoque recomendado para Bitbucket Pipelines, ya que la configuración de verificaciones de CI requeridas de Orbit funciona con nombres de trabajos de GitHub Actions o una pipeline de GitLab, no con Bitbucket.
Si necesitas más que "desplegar el branch head", usa un token API en lugar de un hook. Orbit, luego Tokens, crea tokens bearer limitados para CI/CD con una API REST documentada y un workflow de GitHub Actions listo para usar. El acceso API está incluido en el plan Apex.
Reconstruir en un Horario Sin un Hook
Si todo lo que quieres es una reconstrucción periódica, no necesitas un hook en absoluto. Scheduled rebuild en Settings, bajo Runtime, reconstruye la producción automáticamente cada hora, cada 6 horas, cada 12 horas, diariamente, cada 2 días o semanalmente. Está construido exactamente para el caso del sitio impulsado por CMS y no hay URL secreta que proteger.
Verificar la Actividad del Hook
Cada fila de hook muestra cuántas veces se ha utilizado y cuándo se utilizó por última vez, en la forma "Used 14 times, last 3 Jul". Esta es la forma más rápida de confirmar que tu CMS realmente está llamando al hook cuando crees que lo está.
Si el contador no aumenta, el problema está del lado de la llamada: verifica que el método sea POST, que la URL sea exacta y que la integración no esté fallando silenciosamente en un error de TLS o firewall.
Eliminar un Hook
Haz clic en Delete hook en la fila y confirma. El diálogo advierte que cualquier servicio que lo use dejará de funcionar, que es exactamente lo que sucede.
No hay forma de rotar el token de un hook en su lugar. Si una URL se filtra, eliminas el hook y creas uno nuevo, luego actualizas todos los sistemas que usaban la URL anterior. La eliminación surte efecto de inmediato, así que planifica el cambio antes de eliminar en lugar de después.
Solución de Problemas
Nada sucede cuando llamo al hook. Verifica que el método sea POST. Comprueba la URL carácter por carácter, incluido el token. Comprueba el contador de uso del hook en la pestaña Hooks: si no está aumentando, la solicitud nunca llegó.
El hook devuelve un error sobre el commit más reciente. Orbit no pudo leer el branch head desde tu proveedor de git. Reconecta el proveedor desde Orbit, luego New project, luego Reconnect, y confirma que el repositorio sigue siendo accesible.
El hook devuelve un error sobre el ambiente objetivo. El ambiente al que señalaba el hook ya no existe, muy probablemente porque se eliminó un ambiente de staging. Elimina el hook y crea uno nuevo contra un ambiente activo.
El hook se dispara pero la implementación es la misma que la última vez. Ese es el comportamiento de deduplicación: el branch head no ha cambiado, así que no hay nada nuevo para compilar. Haz un push de un commit, o usa Deploy now si específicamente quieres reconstruir el mismo commit.
Lecturas Relacionadas
- Deploying Your Project para las compuertas de implementación y cuáles de ellas los hooks eluyen
- Connecting a Bitbucket Repo para el caso de gating de CI que los hooks resuelven
- Environment Variables, ya que una compilación activada por hook lee la misma configuración que cualquier otra