> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab 告警集成

> 通过 Webhook 将 GitLab 的流水线失败、部署失败和安全漏洞同步到 Flashduty On-call，修复后自动恢复。

通过 GitLab 项目或群组的 Webhook，将流水线（Pipeline）失败、部署（Deployment）失败和安全漏洞（Vulnerability）同步到 Flashduty On-call。每个分支或标签、每个环境、每个漏洞各对应一条 Flashduty 告警：分支的流水线失败时触发、之后该分支有流水线成功时恢复；环境部署失败时触发、之后部署成功时恢复；漏洞被发现时触发、被解决或忽略时恢复。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **GitLab**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **GitLab**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 GitLab 中配置

***

GitLab.com、GitLab 自托管版和 GitLab Dedicated 都支持 Webhook。项目 Webhook 所有版本都有，需要项目的 Maintainer 或 Owner 角色；群组 Webhook 需要 Premium 或 Ultimate 版本和群组的 Owner 角色，会推送群组及其子群组下所有项目的事件。

<Steps>
  <Step title="添加 Webhook">
    1. 在 GitLab 中打开需要接入的项目（或群组），在左侧导航选择 **Settings → Webhooks**
    2. 点击 **Add new webhook**
    3. 将 Flashduty 集成的完整推送地址粘贴到 **URL**，地址中需包含 `integration_key`
    4. **Signing token** 和 **Secret token** 可以不填，Flashduty 通过地址中的 `integration_key` 认证
    5. 不要填写 **Custom webhook template**，Flashduty 按 GitLab 默认的请求体解析
  </Step>

  <Step title="选择推送的事件">
    在 **Trigger** 中勾选以下事件，其余事件不需要勾选，勾选了 Flashduty 也会直接返回成功、不创建告警：

    | GitLab 事件 | 在 Flashduty 中的效果 |
    | :- | :- |
    | **Pipeline events** | 流水线状态为 `failed` 时触发该分支（或标签）的告警，状态为 `success` 时恢复；`pending`、`running`、`canceled` 等状态不处理 |
    | **Deployment events** | 部署状态为 `failed` 时触发该环境的告警，状态为 `success` 时恢复；`running`、`canceled`、`blocked` 以及审批通过（`approved`）、驳回（`rejected`）不处理 |
    | **Vulnerability events** | 漏洞状态为 `detected`（待处理）或 `confirmed`（已确认）时触发该漏洞的告警，状态为 `resolved`（已解决）或 `dismissed`（已忽略）时恢复 |

    Vulnerability events 需要 GitLab 17.11 或更高版本（17.7 到 17.10 需要管理员开启 `vulnerabilities_as_webhook_events` 功能开关），项目中产生漏洞记录需要 GitLab Ultimate。
  </Step>

  <Step title="保存并验证">
    1. 保持 **Enable SSL verification** 勾选，点击 **Add webhook**
    2. 在 Webhook 列表中点击 **Test**，选择 **Pipeline events**。GitLab 会把项目最近一条流水线的真实数据推送过来：如果这条流水线失败，Flashduty 会为它所在的分支创建一条告警；如果成功，不会产生新告警
    3. 让一个分支的流水线失败（例如提交一个会失败的测试），确认 Flashduty 收到活动告警；修复后在同一分支重新运行成功，确认原告警恢复

    **Test** 默认的 **Push events** 以及其他与本集成无关的事件，Flashduty 会返回成功、不创建告警。GitLab 不支持用 **Test** 发送部署事件；**Vulnerability events** 的测试会推送项目中的一条真实漏洞，如果它处于待处理或已确认状态，会创建对应的告警。
  </Step>
</Steps>

## Alert Key

***

Flashduty 按业务对象生成 Alert Key，同一对象的触发和恢复事件使用同一个 Alert Key：

| 对象 | 使用的字段 | 说明 |
| :- | :- | :- |
| 分支或标签的流水线 | `project.id`、`object_attributes.tag`、`object_attributes.ref` | 同一分支上后续的流水线（包括重试）都合并到这条告警，任何一条成功就恢复 |
| 环境的部署 | `project.id`、`environment` | 同一环境后续的部署合并到这条告警，任何一次成功就恢复 |
| 漏洞 | `object_attributes.url` 末尾的漏洞 ID | 漏洞的标题、等级、关联 Issue 变化不改变 Alert Key |

Alert Key 由对象类型和上表字段共同计算，分支和同名标签、分支和同名环境不会互相合并。项目改名或迁移路径不影响 Alert Key。缺少上表字段的失败或成功事件会被拒绝。

## 状态和告警等级

***

| 事件 | 状态 | Flashduty 等级 |
| :- | :- | :- |
| 流水线 `failed` | 触发 | Warning |
| 部署 `failed`，环境层级（`environment_tier`）为 `production` | 触发 | Critical |
| 部署 `failed`，其他环境 | 触发 | Warning |
| 漏洞 `detected` / `confirmed`，严重程度 `critical` 或 `high` | 触发 | Critical |
| 漏洞 `detected` / `confirmed`，严重程度 `medium` | 触发 | Warning |
| 漏洞 `detected` / `confirmed`，严重程度 `low`、`info`、`unknown` | 触发 | Info |
| 流水线 `success`、部署 `success`、漏洞 `resolved` / `dismissed` | 恢复 | - |

## 告警不会自动恢复的情况

***

以下对象之后不会再有成功事件，告警不会自动恢复：

* 流水线失败后分支被删除或合并，或失败的是标签流水线
* 失败的是临时环境（例如 Review App 的 `review/*` 环境），之后环境被停止
* 同一分支上一条较早的流水线在较新的成功流水线之后才结束并失败

建议在协作空间开启[超时自动关闭](/zh/on-call/channel/create-edit)，超时计时起点选 **故障触发**，超时时长建议 24 小时。流水线和部署的正常修复一般在一个工作日内完成；漏洞告警会在漏洞被解决或忽略时恢复，如果协作空间只接收漏洞告警，可以不开启。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `event` | 事件类型：`pipeline`、`deployment` 或 `vulnerability` |
| `project` / `project_id` | 项目路径（如 `group/project`）和 ID；漏洞事件只有 `project_id` |
| `ref` / `ref_type` | 流水线或部署的分支、标签名，`ref_type` 为 `branch` 或 `tag` |
| `pipeline_id` / `pipeline_status` / `pipeline_source` | 流水线 ID、状态和触发来源（如 `push`、`schedule`、`merge_request_event`） |
| `failed_jobs` | 失败的作业名，逗号分隔，不含允许失败（`allow_failure`）的作业 |
| `sha` / `commit_title` | 提交 SHA 和提交标题 |
| `user` | 触发流水线或部署的用户名 |
| `env` / `environment_tier` / `environment_url` | 部署的环境名、环境层级和环境外部地址 |
| `deployment_id` / `deployment_status` | 部署 ID 和状态 |
| `vulnerability_id` / `state` / `severity` | 漏洞 ID、状态和 GitLab 中的严重程度 |
| `report_type` / `scanner` | 发现漏洞的扫描类型（如 `sast`、`dependency_scanning`）和扫描器 |
| `identifiers` | 漏洞标识，如 CVE 编号，逗号分隔 |
| `file` / `image` / `package` / `package_version` | 漏洞所在文件、容器镜像、依赖包及版本 |
| `url` | GitLab 中对应流水线、部署作业或漏洞页面的链接 |

流水线变量（`variables`）和用户邮箱不会写入标签。

## 排查问题

***

* **Webhook 显示 Temporarily disabled 或 Disabled**：GitLab 在连续 4 次推送失败后会临时停用 Webhook，连续 40 次失败后永久停用。确认推送地址完整且包含 `integration_key`，然后点击 **Test** 发送一次测试请求重新启用
* **部署被驳回后收到告警**：受保护环境的部署被驳回时，GitLab 先推送 `rejected`，丢弃部署作业后再推送同一部署的 `failed`，Flashduty 会按部署失败创建告警，可手动关闭或等下一次成功部署恢复
* **合并请求流水线合并到了分支告警**：合并请求流水线的 `ref` 是源分支名，和该分支的普通流水线使用同一个 Alert Key
* **没有收到漏洞事件**：确认 GitLab 版本和 Ultimate 订阅满足要求，并且项目已开启安全扫描
* **在 Webhook 的 Recent events 中查看推送记录**：在 Webhook 编辑页的 **Recent events** 中可以查看每次推送的请求体和 Flashduty 返回的响应

更多字段含义请参阅 [GitLab Webhook 事件](https://docs.gitlab.com/user/project/integrations/webhook_events/)。