> ## 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.

# Gitea 变更集成

> 通过 Gitea Webhook 将 Gitea Actions 工作流运行和 Release 发布同步到 Flashduty On-call，作为变更事件与告警、故障关联。

<Tip>**版本要求**：此功能需要 On-call 标准版及以上订阅。[了解更多](https://flashcat.cloud/flashduty/price/)</Tip>

通过 Gitea 仓库或组织的 Webhook，将 Gitea Actions 的工作流运行（Workflow Run）和 Release 发布同步到 Flashduty On-call。每一次工作流运行、每一个 Release 对应一条 Flashduty 变更；工作流运行从执行到成功、失败或取消的每个状态，都会更新同一条变更。

Gitea 的 Webhook 不能按工作流或分支过滤工作流运行（**分支过滤** 只对推送和分支事件生效）：接入后仓库中每个工作流的运行都会成为变更，包括只做构建或测试的工作流。请用 `workflow`、`ref` 标签在 Flashduty 中路由或筛选出部署类运行。

本页适用于 Gitea。Forgejo 的 Actions 事件名称和内容与 Gitea 不同，暂不支持，可使用[自定义变更事件](/zh/on-call/integration/change-integration/custom-event)接入。

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

  ***

  1. 进入 Flashduty 控制台，选择 **集成中心 → 变更事件**
  2. 选择 **Gitea**，填写集成名称
  3. 如需把变更分派到指定协作空间，在集成的 **路由** 中按标签（例如 `repo`、`workflow`）配置规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Gitea 中配置

***

<Steps>
  <Step title="打开 Webhook 设置">
    * 仓库级：进入仓库 **设置 → Webhooks**，点击 **添加 Webhook → Gitea**
    * 组织级：进入组织 **设置 → Webhooks**，点击 **添加 Webhook → Gitea**，组织下所有仓库的事件都会推送

    需要仓库或组织的管理员权限。仓库需要已启用 Gitea Actions，并有可用的 Runner。
  </Step>

  <Step title="填写推送地址">
    1. **目标 URL（Target URL）**：粘贴 Flashduty 集成的完整推送地址
    2. **HTTP 方法**：选择 `POST`
    3. **POST 内容类型**：选择 `application/json`（选择 `application/x-www-form-urlencoded` 同样可以接收）
    4. **密钥（Secret）**：留空即可，Flashduty 通过推送地址中的 `integration_key` 鉴权
  </Step>

  <Step title="选择事件">
    1. 在 **触发条件** 中选择 **自定义事件…**
    2. 勾选 **Workflow Run** 和 **Release**，取消其他事件；不要勾选 **Workflow Jobs**，它不会生成变更
    3. **分支过滤** 留空，它对工作流运行不生效
    4. 保持 **激活** 勾选，点击 **添加 Webhook**
  </Step>
</Steps>

Gitea 的 **测试推送事件（Test Push Event）** 发送的是模拟的 `push` 事件，Flashduty 返回成功但不会生成变更。

## 一条变更是什么

***

| Gitea 对象 | 变更标识（change\_key） | 说明 |
| - | - | - |
| 工作流运行 | `run:<workflow_run.id>` | 同一次运行的执行、结束事件更新同一条变更；同一工作流在同一分支上的两次运行是两条变更。重新运行（rerun）沿用同一个运行 ID，会更新原来的变更，变更从结束状态回到 Processing，`run_attempt` 标签记录第几次尝试 |
| Release | `release:<release.id>` | 发布、删除同一个 Release 更新同一条变更 |

## 状态映射

***

| Gitea 事件 | Gitea 状态 | Flashduty 变更状态 |
| - | - | - |
| workflow\_run，`requested` | `waiting`（等待维护者批准运行） | Planned |
| workflow\_run，`in_progress` | 运行中（包括正在取消） | Processing |
| workflow\_run，`completed` | `success` | Done |
| workflow\_run，`completed` | `failure` | Failed |
| workflow\_run，`completed` | `cancelled` | Canceled |
| workflow\_run，`completed` | `skipped`（所有任务都被跳过，没有实际执行） | Canceled |
| release | published | Done |
| release | deleted | Canceled |

Done、Failed 和 Canceled 是结束状态，Flashduty 会记录变更结束时间。

以下推送返回成功但不生成变更：Gitea 的其他事件类型（包括 `workflow_job` 和测试推送事件产生的 `push`）、Release 的 `updated` 动作、草稿状态的 Release，以及排队中的运行（状态为 `queued`、`pending` 或 `requested` 的 `requested` 事件；变更从运行开始时才产生）。

## 变更内容

***

| 字段 | 工作流运行 | Release |
| - | - | - |
| 标题 | `<仓库>: <工作流> on <分支> (<短 SHA>)` | `<仓库>: release <tag>` |
| 描述 | 运行的显示标题（提交信息或合并请求标题） | Release 名称（与 tag 相同时为空） |
| 链接 | 该次运行的页面，没有时为仓库的 Actions 页面 | Release 页面 |

标签可用于路由和在变更列表中筛选：

| 标签 | 工作流运行 | Release |
| - | - | - |
| `repo` | 仓库全名，例如 `octo-org/hello-world` | 同左 |
| `workflow` | 工作流名称，通常是工作流文件名，例如 `deploy.yaml` | — |
| `ref` | 运行的分支 | Release 的目标分支或提交 |
| `sha` | 运行对应的完整提交 SHA | — |
| `version` | — | Release tag |
| `trigger` | 触发运行的事件，例如 `push`、`schedule`、`workflow_dispatch` | — |
| `actor` | 触发运行的用户 | 发布者 |
| `run_id` / `release_id` | Gitea 对象 ID | Gitea 对象 ID |
| `run_attempt` | 第几次尝试 | — |
| `state` | 最新的运行状态；运行结束后为 `success`、`failure`、`cancelled` 或 `skipped` | — |
| `prerelease` | — | 预发布时为 `true` |

## 常见问题

***

<AccordionGroup>
  <Accordion title="为什么没有收到工作流变更？">
    * 确认 Webhook 勾选了 **Workflow Run**，且所用的 Gitea 版本提供该事件
    * 在 Webhook 页面的推送记录中查看请求和 Flashduty 的响应
  </Accordion>

  <Accordion title="在 Gitea 中重放（Replay）推送会重复记录吗？">
    不会。同一状态、同一时间的事件只记录一次。
  </Accordion>

  <Accordion title="为什么所有工作流都变成了变更？">
    Gitea 不能按工作流筛选 Webhook 事件。**分支过滤** 对工作流运行同样不生效。请在集成的 **路由** 中按 `workflow` 或 `ref` 标签把部署类工作流分派到对应协作空间。
  </Accordion>

  <Accordion title="推送返回 InvalidParameter 错误？">
    * `unsupported action`、`unsupported workflow_run.status` 或 `unsupported workflow_run.conclusion`：收到了 Flashduty 尚未支持的运行状态，请联系我们
    * `workflow_run.id is missing` 或 `release.id is missing`：推送内容不完整，请确认推送来自 Gitea 原生 Webhook
  </Accordion>
</AccordionGroup>