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。前置条件开始搭建前需要准备三样东西一个 GitHub 仓库Issue 将被提交到这个仓库中。一个有建 Issue 权限的 Token二选一细粒度 PATFine-grained PAT限定到目标仓库授予Issues: Read and write权限经典 PATClassic PAT包含repo作用域。可在 github.com/settings/tokens 创建。一个 OneUptime 项目在该项目下创建 Workflow。第一步用全局变量安全存储 TokenToken 属于敏感凭证绝不能直接写进工作流的某个块里。正确的做法是利用 Workflow 的**全局变量Global Variables**机制进入Workflows → Global Variables → Create。变量命名为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块将其输入与触发器输出相连然后按下表配置配置项值MethodPOSTURLhttps://api.github.com/repos/your-org/your-repo/issuesHeaders请求头Authorization: Bearer {{variable.GITHUB_TOKEN}} Accept: application/vnd.githubjson X-GitHub-Api-Version: 2022-11-28 User-Agent: OneUptimeBody请求体{ title: OneUptime incident: {{Incident.title}}, body: {{Incident.description}}\n\nFiled automatically from OneUptime., labels: [incident, oneuptime] }几个要点说明Authorization头通过全局变量引用 Token配合 Bearer 方案发送这是集成总览文档中出站集成认证速查表所列的通用形式。Accept: application/vnd.githubjson是 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 ServerGHES如果使用企业版 GitHub将 URL 前缀替换为你的实例地址路径结构保持不变https://your-host/api/v3/repos/{owner}/{repo}/issues指定负责人与里程碑在请求体中追加assigneesGitHub 用户名数组与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形成闭环读取 API 块输出{{CreateIssue.response-body.html_url}}其中CreateIssue是 API 块的 Identifierresponse-body 是其返回值详见变量文档添加一个Update Incident块将该值写入事件的自定义字段或描述中。这样工程师在 OneUptime 事件详情里就能直接看到对应的 GitHub Issue 链接。故障排查Troubleshooting错误含义与处理401Token 错误或已过期。细粒度 Token 必须显式授予目标仓库及Issues权限经典 Token 需要repo作用域。403/ 限流检查是否携带User-Agent头GitHub 拒绝无 UA 的请求并确认未触发 API 速率限制。404owner/repo路径拼写错误或 Token 无法访问私有仓库。422引用了不存在的标签不会报错GitHub 会自动创建被引用的标签但请求体格式错误会报此错——检查 JSON 语法。排查时优先查看该次运行的Full Log原始日志其中会标注未解析的变量引用若某个变量值看起来为空对照Steps的Received面板检查引用是否拼写正确注意是块的 Identifier 而非显示名称且local.components路径不可拼错。自托管部署的网络要求如果你以自托管方式部署 OneUptime本工作流需要以下网络条件详见自托管 GitHub 集成出站方向OneUptime 到api.github.com的 DNS 解析与出站 HTTPSTCP 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考