Vercel
La integracion con Vercel conecta tus despliegues con Almirant, permitiendo ver URLs de preview directamente en los work items y hacer seguimiento del estado de cada deployment sin salir de la plataforma.
Como funciona
La integracion se basa en un webhook de Vercel que notifica a Almirant cada vez que ocurre un despliegue. Cuando Vercel despliega una nueva version de tu aplicacion, envia un evento al webhook de Almirant con la informacion del deployment, incluyendo la URL de preview y el estado.
Vercel despliega --> Webhook notifica a Almirant --> Almirant actualiza el work item
Configurar la integracion
1. Obtener el webhook secret
Un administrador de tu organizacion debe configurar la variable de entorno VERCEL_WEBHOOK_SECRET en el backend de Almirant. Este secreto se usa para verificar que las notificaciones provienen realmente de Vercel.
2. Configurar el webhook en Vercel
- Accede a tu proyecto en el dashboard de Vercel.
- Ve a Settings > Webhooks.
- Haz clic en Create Webhook.
- Configura los siguientes campos:
| Campo | Valor |
|---|---|
| URL | https://tu-dominio-almirant.com/webhooks/vercel |
| Secret | El mismo valor configurado en VERCEL_WEBHOOK_SECRET |
| Events | deployment.created, deployment.succeeded, deployment.failed, deployment.canceled |
- Guarda el webhook.
3. Verificar la conexion
Realiza un despliegue de prueba en Vercel y verifica que Almirant recibe la notificacion. Puedes comprobar los logs del webhook en la configuracion de Almirant.
URLs de preview en work items
Cuando un despliegue de Vercel esta vinculado a un work item (a traves de la referencia en el commit o branch), Almirant muestra la URL de preview directamente en el detalle del work item. Esto permite a los miembros del equipo acceder rapidamente al entorno de preview para revisar los cambios.
Informacion visible
En cada work item vinculado a un deployment, veras:
| Dato | Descripcion |
|---|---|
| URL de preview | Enlace directo al despliegue de preview |
| Estado | Estado del deployment (building, ready, error, canceled) |
| Branch | Rama de Git desde la que se realizo el despliegue |
| Fecha | Fecha y hora del despliegue |
Estados de despliegue
Almirant refleja los estados de despliegue de Vercel en tiempo real:
| Estado | Significado |
|---|---|
| Building | El despliegue esta en progreso |
| Ready | El despliegue se completo exitosamente y la URL de preview esta disponible |
| Error | El despliegue fallo durante el proceso de build |
| Canceled | El despliegue fue cancelado manualmente |
Buenas practicas
Usa nombres de branch que incluyan el identificador del work item (por ejemplo feature/A-T-42-notificaciones) para que Almirant vincule automaticamente los despliegues al work item correspondiente.
- Configura webhooks por proyecto -- Si tienes multiples proyectos en Vercel, configura un webhook para cada uno apuntando al mismo endpoint de Almirant.
- Usa el webhook secret -- Siempre configura un secreto para verificar la autenticidad de las notificaciones.
- Monitoriza los logs -- Revisa periodicamente los logs de webhooks para detectar errores de comunicacion.
Variable de entorno
| Variable | Descripcion | Obligatoria |
|---|---|---|
VERCEL_WEBHOOK_SECRET | Secreto compartido para verificar la firma de los webhooks de Vercel | Si |
Endpoint del webhook
El endpoint que recibe las notificaciones de Vercel es:
POST /webhooks/vercel
Headers:
x-vercel-signature: <firma-hmac>
Body: JSON con el payload del evento de despliegue
El backend verifica la firma HMAC del payload usando VERCEL_WEBHOOK_SECRET antes de procesar el evento. Si la firma no coincide, el webhook se rechaza con un 401.
Flujo de procesamiento
- Vercel envia el evento al endpoint
/webhooks/vercel. - El backend verifica la firma HMAC del payload.
- Se extrae la informacion del deployment (URL, estado, branch, commit).
- Si el commit o branch contiene una referencia a un work item, se vincula automaticamente.
- La informacion del deployment se almacena y se muestra en el detalle del work item.