Vercel

L'intégration Vercel connecte vos déploiements à Almirant, ce qui permet d'afficher des URL de preview directement dans les work items et de suivre l'état de chaque deployment sans quitter la plateforme.

Fonctionnement

L'intégration repose sur un webhook Vercel qui notifie Almirant à chaque déploiement. Lorsque Vercel déploie une nouvelle version de votre application, il envoie un événement au webhook Almirant avec les informations du deployment, y compris l'URL de preview et son état.

Vercel despliega --> Webhook notifica a Almirant --> Almirant actualiza el work item

Configurer l'intégration

1. Obtenir le webhook secret

Un administrateur de votre organisation doit configurer la variable d'environnement VERCEL_WEBHOOK_SECRET dans le backend d'Almirant. Ce secret sert à vérifier que les notifications proviennent bien de Vercel.

2. Configurer le webhook dans Vercel

1. Accédez à votre projet dans le dashboard Vercel.
2. Accédez à Settings > Webhooks.
3. Cliquez sur Create Webhook.
4. Configurez les champs suivants :

Champ	Valeur
URL	https://tu-dominio-almirant.com/webhooks/vercel
Secret	La même valeur que celle configurée dans VERCEL_WEBHOOK_SECRET
Events	deployment.created, deployment.succeeded, deployment.failed, deployment.canceled

5. Enregistrez le webhook.

3. Vérifier la connexion

Effectuez un déploiement de test dans Vercel et vérifiez qu'Almirant reçoit la notification. Vous pouvez consulter les logs du webhook dans la configuration d'Almirant.

URL de preview dans les work items

Lorsqu'un déploiement Vercel est lié à un work item (par une référence dans le commit ou la branch), Almirant affiche l'URL de preview directement dans le détail du work item. Les membres de l'équipe peuvent ainsi accéder rapidement à l'environnement de preview pour réviser les modifications.

Informations visibles

Dans chaque work item lié à un deployment, vous verrez :

Donnée	Description
URL de preview	Lien direct vers le déploiement de preview
État	État du deployment (building, ready, error, canceled)
Branch	Branche Git depuis laquelle le déploiement a été effectué
Date	Date et heure du déploiement

États de déploiement

Almirant reflète les états de déploiement de Vercel en temps réel :

État	Signification
Building	Le déploiement est en cours
Ready	Le déploiement s'est terminé avec succès et l'URL de preview est disponible
Error	Le déploiement a échoué pendant le processus de build
Canceled	Le déploiement a été annulé manuellement

Bonnes pratiques

Noms de branch

Utilisez des noms de branch qui incluent l'identifiant du work item (par exemple, feature/A-T-42-notificaciones) afin qu'Almirant lie automatiquement les déploiements au work item correspondant.

• Configurez des webhooks par projet -- Si vous avez plusieurs projets dans Vercel, configurez un webhook pour chacun d'eux vers le même endpoint Almirant.
• Utilisez le webhook secret -- Configurez toujours un secret pour vérifier l'authenticité des notifications.
• Surveillez les logs -- Consultez régulièrement les logs des webhooks pour détecter les erreurs de communication.

Pour les développeurs

Variable d'environnement

Variable	Description	Obligatoire
VERCEL_WEBHOOK_SECRET	Secret partagé permettant de vérifier la signature des webhooks Vercel	Oui

Endpoint du webhook

L'endpoint qui reçoit les notifications Vercel est :

POST /webhooks/vercel
Headers:
  x-vercel-signature: <firma-hmac>
Body: JSON con el payload del evento de despliegue

Le backend vérifie la signature HMAC du payload à l'aide de VERCEL_WEBHOOK_SECRET avant de traiter l'événement. Si la signature ne correspond pas, le webhook est rejeté avec un 401.

Flux de traitement

1. Vercel envoie l'événement à l'endpoint /webhooks/vercel.
2. Le backend vérifie la signature HMAC du payload.
3. Les informations du deployment (URL, état, branch, commit) sont extraites.
4. Si le commit ou la branch contient une référence à un work item, ils sont liés automatiquement.
5. Les informations du deployment sont stockées et affichées dans le détail du work item.