OneUptime GitHub 集成实战：事件创建时通过 Workflow 自动提交 GitHub Issue

OneUptime GitHub 集成实战：事件创建时通过 Workflow 自动提交 GitHub Issue

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

当 OneUptime 检测到故障并创建一条 Incident（事件）时，如果能自动在 GitHub 仓库中开出一条 Issue，工程跟进就会沉淀在受影响服务所属的代码仓库里，而不是散落在告警平台中。本文基于 OneUptime 官方集成文档，完整讲解如何用内置的 Workflow（自动化工作流）搭建这条「事件 → GitHub Issue」流水线：从 Token 前置条件、全局变量存储、画布配置到运行日志验证与故障排查，并给出源码级原理佐证，读完即可在自己的 OneUptime 项目中落地。

集成模式：单向出站（Outbound）调用

这条 GitHub 集成属于典型的出站集成：OneUptime 主动调用 GitHub REST API 的创建 Issue 接口，不需要 GitHub 反向回调 OneUptime。整套逻辑建立在 OneUptime 内置的 Workflow 自动化引擎之上，无需安装任何独立插件，全部在拖拽画布上完成。

数据流如下：

OneUptime Incident → On Create ──► API component (POST /repos/{owner}/{repo}/issues) ──► GitHub issue

• 触发器（Trigger）：选择Incident → On Create，即事件被创建的那一刻触发。
• 组件（Component）：选择API组件，向 GitHub 发送 REST 请求。

这套「OneUptime 事件触发器 + API 组件」的出站模式，在集成总览文档中被定义为所有出站集成的通用范式——Jira、PagerDuty、ServiceNow、GitLab 均复用同一套路，只有 URL 与 Payload 不同。因此掌握了本案例，也就掌握了 OneUptime 对接任何带 REST API 的外部系统的能力。

从源码角度，Incident 模型通过@EnableWorkflow({ create: true, delete: true, update: true, read: true })注解开放了工作流能力（见 Incident.ts），意味着事件的创建、更新、删除都会成为可监听的工作流事件；而事件对象的title（标题）与description（描述，Markdown 格式，可见于状态页）字段正是后续 Issue 内容的数据来源（见 Incident.ts）。

注意区分两条 GitHub 连接：本文只讨论「事件 → 提交 Issue」。OneUptime 另有一条原生的GitHub App集成，用于连接代码仓库（供 AI Agent 与代码功能使用），可让用户在 Issue 或 PR 中 @ 提及机器人完成实现、修订或评审。二者不冲突，本文不展开 GitHub App 部分，相关安装与配置见自托管 GitHub 集成与从 GitHub 使用 OneUptime。

前置条件

开始搭建前，需要准备三样东西：

1. 一个 GitHub 仓库：Issue 将被提交到这个仓库中。

2. 一个有建 Issue 权限的 Token，二选一：

   • 细粒度 PAT（Fine-grained PAT）：限定到目标仓库，授予Issues: Read and write权限；
   • 经典 PAT（Classic PAT）：包含repo作用域。

   可在 github.com/settings/tokens 创建。

3. 一个 OneUptime 项目：在该项目下创建 Workflow。

第一步：用全局变量安全存储 Token

Token 属于敏感凭证，绝不能直接写进工作流的某个块里。正确的做法是利用 Workflow 的**全局变量（Global Variables）**机制：

1. 进入Workflows → Global Variables → Create。
2. 变量命名为GITHUB_TOKEN，粘贴 Token，并开启Is Secret开关。

设置 Secret 后，该变量的值会在运行日志与步骤追踪中被自动擦除（scrub）。这一点有源码佐证：Workflow 运行器在持久化运行轨迹前会递归清洗所有秘密变量的值（见 RunWorkflow.ts 与 SecretRedaction.ts），即使秘密值混入 JSON 结构的键名或错误信息，也会一并脱敏。也就是说，你的 Token 既不会出现在工作流定义中，也不会残留在任何一次运行的日志里。

在任意块的文本字段中，通过{{global.variables.GITHUB_TOKEN}}即可引用该变量（详见变量文档）。注意变量名区分大小写，且带空格的引用（如{{ global.variables.GITHUB_TOKEN }}）无法解析——引用写错时不会报错，而是作为字面文本原样传递，因此务必使用编辑器内置的变量选择器（picker）来插入引用。

第二步：构建「事件 → GitHub Issue」工作流

创建并命名工作流

进入Workflows → Create Workflow，命名为Incidents → GitHub Issues，打开Builder画布。

添加 Incident 触发器

从Add Trigger面板添加一个Incident触发器，事件设为On Create，并将块重命名为Incident（便于后续引用其输出）。

触发器选定后，On Create Incident会把完整的 Incident 记录传递给下一个块——标题、描述、严重级别等字段均可直接读取。更精确地说，这类记录型触发器对外暴露一个名为model的返回值，通过{{Incident.title}}、{{Incident.description}}即可取到对应字段（详见触发器文档）。

添加 API 块并连接触发器

添加一个API块，将其输入与触发器输出相连，然后按下表配置：

Headers（请求头）：

Authorization: Bearer {{variable.GITHUB_TOKEN}} Accept: application/vnd.github+json X-GitHub-Api-Version: 2022-11-28 User-Agent: OneUptime

Body（请求体）：

{ "title": "OneUptime incident: {{Incident.title}}", "body": "{{Incident.description}}\n\nFiled automatically from OneUptime.", "labels": ["incident", "oneuptime"] }

几个要点说明：

• Authorization头通过全局变量引用 Token，配合 Bearer 方案发送；这是集成总览文档中出站集成认证速查表所列的通用形式。
• Accept: application/vnd.github+json是 GitHub REST API 的标准媒体类型；X-GitHub-Api-Version: 2022-11-28锁定 API 版本；User-Agent头为必填——GitHub 会直接拒绝不带 User-Agent 的请求。
• 请求体中的title、body使用了来自触发器的变量插值，\n\n用于在描述后追加一行空行与签名文本；labels数组可以预置incident、oneuptime等标签。
• 变量可以出现在 JSON 字段的字符串值内部，但不能作为 JSON 的键（详见变量文档），上面的用法完全合规。

保存、启用并测试

点击Save保存工作流，然后在Overview页面打开Enabled开关——新建的工作流默认是禁用状态，禁用状态下的工作流连手动运行都会被拒绝。随后创建一条测试 Incident：

• 若工作流运行日志中出现201 Created，说明 Issue 已成功创建；
• 响应体中包含新 Issue 的number（编号）与html_url（链接地址），可在运行日志的 API 块步骤中查看。

验证与运行日志

API 块是验证整条链路的关键观察点。根据运行日志文档：

• 在Workflows → Runs & Logs或单个工作流的Runs & Logs页面查看每次执行记录，状态为Executed表示工作流顺利执行到结尾。
• 打开单次运行的View Logs，在Steps标签页中展开 API 块：Received展示变量解析后的实际请求配置，Returned展示 GitHub 返回的状态码与响应体。
• 注意一个细节：API 块收到非 2xx 响应时会走Error输出分支，但整条运行仍会以Executed收尾，只是该步骤在画布上标红——排查时不要只看运行总状态。
• 在Builder页面点击Run Workflow手动触发，会实时打开同一个日志视图，便于边运行边观察。

进阶技巧

GitHub Enterprise Server（GHES）

如果使用企业版 GitHub，将 URL 前缀替换为你的实例地址，路径结构保持不变：

https://your-host/api/v3/repos/{owner}/{repo}/issues

指定负责人与里程碑

在请求体中追加assignees（GitHub 用户名数组）与milestone（里程碑编号）：

{ "title": "OneUptime incident: {{Incident.title}}", "body": "{{Incident.description}}\n\nFiled automatically from OneUptime.", "labels": ["incident", "oneuptime"], "assignees": ["octocat"], "milestone": 3 }

将 Issue 链接回写 Incident

建完 Issue 后，把 GitHub 返回的html_url存回 Incident，形成闭环：

1. 读取 API 块输出{{CreateIssue.response-body.html_url}}（其中CreateIssue是 API 块的 Identifier，response-body 是其返回值，详见变量文档）；
2. 添加一个Update Incident块，将该值写入事件的自定义字段或描述中。

这样工程师在 OneUptime 事件详情里就能直接看到对应的 GitHub Issue 链接。

故障排查（Troubleshooting）

排查时优先查看该次运行的Full Log原始日志，其中会标注未解析的变量引用；若某个变量值看起来为空，对照Steps的Received面板检查引用是否拼写正确（注意是块的 Identifier 而非显示名称，且local.components路径不可拼错）。

自托管部署的网络要求

如果你以自托管方式部署 OneUptime，本工作流需要以下网络条件（详见自托管 GitHub 集成）：

• 出站方向：OneUptime 到api.github.com的 DNS 解析与出站 HTTPS（TCP 443）；
• 无需入站：GitHub 不会回调 OneUptime，因此不需要开放入站 Webhook 端口；
• 若使用 GitHub Enterprise Server，出站目标替换为企业实例域名，防火墙配置不会自动适配 GHES 主机名。

延伸阅读

• 集成总览 —— 出入站两种集成模式与认证速查表
• GitLab 集成 —— 同一思路在 GitLab 上的实现
• 自托管 GitHub 集成 —— 原生 GitHub App 连接方式
• 从 GitHub 使用 OneUptime —— 在 Issue 或 PR 中向 GitHub App 下达指令
• Workflow 总览 —— 自动化引擎的工作原理
• 触发器 —— Webhook 与 OneUptime 事件触发器详解
• 组件 —— API 等组件的完整输出列表
• 变量 —— 秘密变量与块间数据传递
• 运行与日志 —— 确认工作流是否按预期触发

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime