Vercel

Die Vercel-Integration verbindet deine Deployments mit Almirant. Dadurch kannst du Preview-URLs direkt in Work Items anzeigen und den Status jedes Deployments verfolgen, ohne die Plattform zu verlassen.

So funktioniert es

Die Integration basiert auf einem Vercel-Webhook, der Almirant bei jedem Deployment benachrichtigt. Wenn Vercel eine neue Version deiner Anwendung bereitstellt, sendet es ein Ereignis mit den Deployment-Informationen, einschließlich Preview-URL und Status, an den Almirant-Webhook.

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

Die Integration einrichten

1. Das Webhook-Secret abrufen

Ein Administrator deiner Organisation muss die Umgebungsvariable VERCEL_WEBHOOK_SECRET im Almirant-Backend konfigurieren. Dieses Secret wird verwendet, um zu prüfen, ob die Benachrichtigungen tatsächlich von Vercel stammen.

2. Den Webhook in Vercel konfigurieren

1. Gehe in deinem Vercel-Dashboard zu deinem Projekt.
2. Gehe zu Settings > Webhooks.
3. Klicke auf Create Webhook.
4. Konfiguriere die folgenden Felder:

Feld	Wert
URL	https://tu-dominio-almirant.com/webhooks/vercel
Secret	Derselbe Wert, der in VERCEL_WEBHOOK_SECRET konfiguriert ist
Events	deployment.created, deployment.succeeded, deployment.failed, deployment.canceled

5. Speichere den Webhook.

3. Verbindung überprüfen

Führe ein Test-Deployment in Vercel aus und prüfe, ob Almirant die Benachrichtigung empfängt. Du kannst die Webhook-Logs in der Almirant-Konfiguration prüfen.

Preview-URLs in Work Items

Wenn ein Vercel-Deployment mit einem Work Item verknüpft ist (über die Referenz im Commit oder Branch), zeigt Almirant die Preview-URL direkt in den Details des Work Items an. Dadurch können Teammitglieder schnell auf die Preview-Umgebung zugreifen, um die Änderungen zu prüfen.

Sichtbare Informationen

In jedem mit einem Deployment verknüpften Work Item siehst du:

Daten	Beschreibung
Preview-URL	Direkter Link zum Preview-Deployment
Status	Status des Deployments (building, ready, error, canceled)
Branch	Git-Branch, aus dem das Deployment erstellt wurde
Datum	Datum und Uhrzeit des Deployments

Deployment-Status

Almirant bildet die Deployment-Status von Vercel in Echtzeit ab:

Status	Bedeutung
Building	Das Deployment wird ausgeführt
Ready	Das Deployment wurde erfolgreich abgeschlossen und die Preview-URL ist verfügbar
Error	Das Deployment ist während des Build-Prozesses fehlgeschlagen
Canceled	Das Deployment wurde manuell abgebrochen

Bewährte Verfahren

Branch-Namen

Verwende Branch-Namen, die die Kennung des Work Items enthalten (zum Beispiel feature/A-T-42-notificaciones), damit Almirant Deployments automatisch mit dem entsprechenden Work Item verknüpft.

• Webhooks pro Projekt konfigurieren -- Wenn du mehrere Projekte in Vercel hast, konfiguriere für jedes einen Webhook, der auf denselben Almirant-Endpunkt zeigt.
• Das Webhook-Secret verwenden -- Konfiguriere immer ein Secret, um die Authentizität der Benachrichtigungen zu prüfen.
• Logs überwachen -- Prüfe die Webhook-Logs regelmäßig, um Kommunikationsfehler zu erkennen.

Für Entwickler

Umgebungsvariable

Variable	Beschreibung	Erforderlich
VERCEL_WEBHOOK_SECRET	Gemeinsames Secret zur Prüfung der Signatur von Vercel-Webhooks	Ja

Webhook-Endpunkt

Der Endpunkt, der Vercel-Benachrichtigungen empfängt, ist:

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

Das Backend prüft die HMAC-Signatur des Payloads mit VERCEL_WEBHOOK_SECRET, bevor es das Ereignis verarbeitet. Wenn die Signatur nicht übereinstimmt, wird der Webhook mit 401 abgelehnt.

Verarbeitungsablauf

1. Vercel sendet das Ereignis an den Endpunkt /webhooks/vercel.
2. Das Backend prüft die HMAC-Signatur des Payloads.
3. Die Deployment-Informationen (URL, Status, Branch, Commit) werden extrahiert.
4. Wenn der Commit oder Branch eine Referenz auf ein Work Item enthält, wird es automatisch verknüpft.
5. Die Deployment-Informationen werden gespeichert und in den Details des Work Items angezeigt.