Vercel
A integração com a Vercel conecta seus deployments ao Almirant, permitindo visualizar URLs de preview diretamente nos work items e acompanhar o status de cada deployment sem sair da plataforma.
Como funciona
A integração se baseia em um webhook da Vercel que notifica o Almirant sempre que ocorre um deployment. Quando a Vercel faz o deployment de uma nova versão da sua aplicação, ela envia um evento ao webhook do Almirant com as informações do deployment, incluindo a URL de preview e o status.
Vercel despliega --> Webhook notifica a Almirant --> Almirant actualiza el work item
Configurar a integração
1. Obter o webhook secret
Um administrador da sua organização deve configurar a variável de ambiente VERCEL_WEBHOOK_SECRET no backend do Almirant. Esse secret é usado para verificar se as notificações realmente vêm da Vercel.
2. Configurar o webhook na Vercel
- Acesse seu projeto no dashboard da Vercel.
- Vá para Settings > Webhooks.
- Clique em Create Webhook.
- Configure os seguintes campos:
| Campo | Valor |
|---|---|
| URL | https://seu-dominio-almirant.com/webhooks/vercel |
| Secret | O mesmo valor configurado em VERCEL_WEBHOOK_SECRET |
| Events | deployment.created, deployment.succeeded, deployment.failed, deployment.canceled |
- Salve o webhook.
3. Verificar a conexão
Faça um deployment de teste na Vercel e verifique se o Almirant recebe a notificação. Você pode consultar os logs do webhook nas configurações do Almirant.
URLs de preview nos work items
Quando um deployment da Vercel está vinculado a um work item (por meio da referência no commit ou branch), o Almirant mostra a URL de preview diretamente nos detalhes do work item. Isso permite que os membros da equipe acessem rapidamente o ambiente de preview para revisar as alterações.
Informações visíveis
Em cada work item vinculado a um deployment, você verá:
| Dado | Descrição |
|---|---|
| URL de preview | Link direto para o deployment de preview |
| Status | Status do deployment (building, ready, error, canceled) |
| Branch | Branch do Git a partir da qual o deployment foi feito |
| Data | Data e hora do deployment |
Status de deployment
O Almirant reflete os status de deployment da Vercel em tempo real:
| Status | Significado |
|---|---|
| Building | O deployment está em andamento |
| Ready | O deployment foi concluído com sucesso e a URL de preview está disponível |
| Error | O deployment falhou durante o processo de build |
| Canceled | O deployment foi cancelado manualmente |
Boas práticas
Use nomes de branch que incluam o identificador do work item (por exemplo, feature/A-T-42-notificacoes) para que o Almirant vincule automaticamente os deployments ao work item correspondente.
- Configure webhooks por projeto -- Se você tiver vários projetos na Vercel, configure um webhook para cada um apontando para o mesmo endpoint do Almirant.
- Use o webhook secret -- Sempre configure um secret para verificar a autenticidade das notificações.
- Monitore os logs -- Revise periodicamente os logs de webhooks para detectar erros de comunicação.
Variável de ambiente
| Variável | Descrição | Obrigatória |
|---|---|---|
VERCEL_WEBHOOK_SECRET | Secret compartilhado para verificar a assinatura dos webhooks da Vercel | Sim |
Endpoint do webhook
O endpoint que recebe as notificações da Vercel é:
POST /webhooks/vercel
Headers:
x-vercel-signature: <firma-hmac>
Body: JSON con el payload del evento de despliegue
O backend verifica a assinatura HMAC do payload com VERCEL_WEBHOOK_SECRET antes de processar o evento. Se a assinatura não corresponder, o webhook será rejeitado com 401.
Fluxo de processamento
- A Vercel envia o evento ao endpoint
/webhooks/vercel. - O backend verifica a assinatura HMAC do payload.
- As informações do deployment (URL, status, branch, commit) são extraídas.
- Se o commit ou a branch contiver uma referência a um work item, ela será vinculada automaticamente.
- As informações do deployment são armazenadas e exibidas nos detalhes do work item.