Vercel
Vercel 集成可将你的部署连接到 Almirant，让你直接在工作项中查看预览 URL，并在不离开平台的情况下跟踪每次 deployment 的状态。
工作原理
该集成基于 Vercel webhook；每次发生部署时，它都会通知 Almirant。Vercel 部署新版应用时，会向 Almirant webhook 发送包含 deployment 信息的事件，其中包括预览 URL 和状态。
Vercel despliega --> Webhook notifica a Almirant --> Almirant actualiza el work item
配置集成
1. 获取 webhook secret
你的组织管理员必须在 Almirant 后端中配置环境变量 VERCEL_WEBHOOK_SECRET。此密钥用于验证通知确实来自 Vercel。
2. 在 Vercel 中配置 webhook
- 前往 Vercel dashboard 中的项目。
- 前往 Settings > Webhooks。
- 点击 Create Webhook。
- 配置以下字段：
| 字段 | 值 |
|---|---|
| URL | https://tu-dominio-almirant.com/webhooks/vercel |
| Secret | 在 VERCEL_WEBHOOK_SECRET 中配置的相同值 |
| Events | deployment.created, deployment.succeeded, deployment.failed, deployment.canceled |
- 保存 webhook。
3. 验证连接
在 Vercel 中进行一次测试部署，并确认 Almirant 收到通知。你可以在 Almirant 配置中检查 webhook 日志。
工作项中的预览 URL
当 Vercel 部署关联到工作项时（通过 commit 或 branch 中的引用），Almirant 会直接在工作项详情中显示预览 URL。这让团队成员可以快速访问预览环境以审查更改。
可见信息
对于每个关联到 deployment 的工作项，你会看到：
| 数据 | 描述 |
|---|---|
| 预览 URL | 指向预览部署的直接链接 |
| 状态 | deployment 状态（building、ready、error、canceled） |
| Branch | 用于部署的 Git 分支 |
| 日期 | 部署日期和时间 |
部署状态
Almirant 会实时反映 Vercel 的部署状态：
| 状态 | 含义 |
|---|---|
| Building | 部署正在进行 |
| Ready | 部署已成功完成，预览 URL 可用 |
| Error | 部署在构建过程中失败 |
| Canceled | 部署被手动取消 |
最佳实践
Branch 命名
使用包含工作项标识符的 branch 名称（例如 feature/A-T-42-notificaciones），以便 Almirant 自动将部署关联到相应工作项。
- 按项目配置 webhook -- 如果在 Vercel 中有多个项目，请为每个项目配置一个指向同一 Almirant endpoint 的 webhook。
- 使用 webhook secret -- 始终配置密钥以验证通知的真实性。
- 监控日志 -- 定期检查 webhook 日志以发现通信错误。
开发者指南
环境变量
| 变量 | 描述 | 必填 |
|---|---|---|
VERCEL_WEBHOOK_SECRET | 用于验证 Vercel webhook 签名的共享密钥 | 是 |
Webhook endpoint
接收 Vercel 通知的 endpoint 为：
POST /webhooks/vercel
Headers:
x-vercel-signature: <firma-hmac>
Body: JSON con el payload del evento de despliegue
后端会在处理事件前使用 VERCEL_WEBHOOK_SECRET 验证 payload 的 HMAC 签名。如果签名不匹配，webhook 会以 401 拒绝。
处理流程
- Vercel 将事件发送到 endpoint
/webhooks/vercel。 - 后端验证 payload 的 HMAC 签名。
- 提取 deployment 信息（URL、状态、branch、commit）。
- 如果 commit 或 branch 包含工作项引用，会自动建立关联。
- deployment 信息会被存储并显示在工作项详情中。