Clowld Space Docs

GitHub 集成

把 pull request 与 Clowld Space 任务关联，并在任务中查看开发进展。

连接 GitHub 后，Clowld Space 根据任务编号自动关联 pull request。任务详情中可直接查看 PR 状态、改动规模、CI 结果和合并冲突。

GitHub 集成只读取安装时授权的仓库，不会提交代码、评论或 status check。

自部署的 Clowld Space 还可以并行连接自托管的 Forgejo、Gitea 或 GitLab 实例，获得同样的 PR 自动关联、合并后转为已完成和 CI 展示，入口在 设置 → 代码，详见自托管 Git 代码托管。Clowld Space 不提供该入口。

工作区 PR 自动完成设置、单任务例外与关联排除已在 1.2.4 正式提供，需要对应的服务端与客户端。

连接 GitHub

工作区 owner 或 admin 可以完成连接：

  1. 打开 设置 → 代码。
  2. 在 GitHub 一行点击 连接 GitHub。
  3. 在 GitHub 中选择账号或组织，并授权全部仓库或指定仓库。
  4. 安装完成后回到 Clowld Space。

连接状态会显示在同一页面。普通成员可以查看状态，但不能连接、断开或修改开关。

GitHub 连接决定 Clowld Space 从哪些仓库接收 PR 事件；代码仓库设置决定智能体执行时可以选择哪些仓库。两者用途不同，需要分别配置。

功能开关

设置 → 代码 的 PR 与任务联动 中有以下设置。在 GitHub 一行的 ⋯ 菜单中选择 暂停 GitHub 功能 后，下面三项开关不再生效，但不会断开 GitHub App。

开关作用
PR 侧栏在任务详情中显示关联的 pull request。
Co-authored-by在智能体创建的 commit 中加入 Co-authored-by: clowld-space-agent <github@clowld.com>。
自动关联 PR分支名或标题含任务编号、或正文中关闭语句后写了任务编号的 PR，会关联到对应任务。
PR 卡片 → CI 与可合并性对每个关联的 PR，Clowld Space 从 GitHub API 拉取一份经鉴权的快照，把它的 CI 状态和可合并性镜像到卡片上（见下方 PR 卡片展示什么）。

在设置 → 代码，通过PR 合并后，任务状态改为选择目标：默认“已完成”、进行中或完成分类的自定义状态，也可以选择“不改变”；不支持“已阻塞”。所有代码托管平台共用此设置。

让 PR 关联到任务

最简单的做法，是把任务编号写进分支名或 PR 标题。例如任务为 CS-123：

cs-123-fix-login-redirect
CS-123 修复登录后的跳转

Clowld Space 会忽略大小写，并且只匹配当前工作区的任务前缀。一个 PR 可以关联多个任务。

只在 PR 正文中写编号时，需要使用 GitHub 的关闭语句：

Closes CS-123
Fixes CS-123
Resolves CS-123

正文中的普通提及，例如 Related to CS-123，不会与该任务建立关联。Commit message 和 PR 评论也不会触发关联。

也可以手动关联：在任务的 Pull requests 区块点 +，粘贴 PR 链接。要把 PR 从任务上移除，打开这一行的 ⋯ 菜单，选择 移除关联；之后 Clowld Space 不会再根据标题或分支把它关联回来。

在任务中查看 PR

关联成功后，PR 会出现在任务详情的 PR 区块。每条记录会显示：

  • 仓库、编号、标题和作者；
  • Open、Draft、Merged 或 Closed 状态；
  • 新增、删除行数和改动文件数；
  • CI 状态：全部通过（带计数）、若干个失败（点名失败的 check），或若干个进行中；没有配置任何 check 的 PR 不显示这一项，"没有 check"不会被当成通过；
  • 可合并性：可合并（仅当 GitHub 报告合并状态为 clean）、有冲突、blocked 或 behind。

CI 状态和可合并性来自 Clowld Space 从 GitHub API 拉取的快照，两者互相独立；已合并或已关闭的 PR 不再显示这两项。GitHub 暂时不可用时，卡片会保留上一次的快照并标记为过期，而不是清空。

PR 列表下方显示目标状态与仍待处理的 PR。缺少关闭语句、工作区选择不改变、任务已到达目标或已结束时，不显示流转提示。

点击记录可以打开 GitHub 上的 PR。关闭 PR 侧栏 只会隐藏这个区块，不会断开连接。

PR 合并后转为已完成的条件

在设置 → 代码，通过PR 合并后，任务状态改为选择目标：默认“已完成”、进行中或完成分类的自定义状态，也可以选择“不改变”；不支持“已阻塞”。所有代码托管平台共用此设置。

只有以下条件同时成立，任务才会改为所选状态：

  1. 至少一个已合并的关联 PR 在标题或正文中使用了紧跟编号的关闭语句，例如 Closes CS-123（Closes login CS-123 这类中间隔词的写法不生效，分支名也不算）；
  2. 没有仍打开或处于草稿状态的关联 PR；关闭但未合并的 PR 保留为记录，不阻止完成；
  3. 任务已受理，当前不是已完成或已取消，尚未达到目标状态，且未开启 Pull requests → ⋯ → 此任务合并后不改状态。

仅在标题或分支中写任务编号只会建立关联。关闭语句必须在合并时存在，事后补写不能触发流转；关闭但未合并的 PR 保留为历史，不阻止流转。

只有 PR 合并、关闭、新增或移除关联等事件触发判断。修改设置或重新打开任务不会追溯改状态；既有工作区保持原来的启用或关闭行为。状态变化写入时间线，不启动智能体执行。

多个工作区

同一个 GitHub App installation 可以连接到多个 Clowld Space 工作区。GitHub 事件会分别进入每个工作区，再按照各自的任务前缀匹配。

例如一个 PR 同时引用 CS-1 和 ENG-2，它可以在两个不同前缀的工作区中分别关联。工作区之间不会看到对方的任务。

如果同一个编号在多个已连接的工作区中都对应到任务（前缀相同时可能出现），Clowld Space 不会在任何一个工作区自动关联，避免合并时完成无关的任务。请在正确的工作区手动关联。

断开连接

在 设置 → 代码 的 GitHub 一行，从 ⋯ 菜单选择 断开，只会移除当前 Clowld Space 工作区与该 installation 的关系，不会替你从 GitHub 卸载 App。已有 PR 记录会保留，新的事件不再进入该工作区。

撤销 GitHub 侧的仓库授权，需到个人或组织的 GitHub App installations 页面卸载或调整仓库范围。卸载后，与该 installation 关联的所有 Clowld Space 工作区都会停止接收事件。

自托管配置

Clowld Space 无需执行本节。自托管需要先创建自己的 GitHub App。

1. 创建 GitHub App

在 GitHub 的 Developer settings → GitHub Apps 中创建 App，并填写：

字段值
Homepage URLClowld Space 前端地址，例如 https://clowld.example.com
Callback URL留空
Setup URLhttps://<api-host>/api/github/setup，并启用 Redirect on update
Webhook URLhttps://<api-host>/api/webhooks/github
Webhook secret一段长期保存的随机字符串

Repository permissions：

权限级别
MetadataRead-only
ContentsRead-only；PR 快照查询需要它，一次读取 head commit、可合并状态与 CI 汇总
Pull requestsRead-only
ActionsRead-only；接收正式发行工作流终态，并订阅晋级 CI 的作业级失败事件
ChecksRead-only；用于显示 CI 状态
Commit statusesRead-only；用于汇总 legacy status 形式的 CI

订阅以下事件：

  • Pull request；
  • Workflow run，用于写回正式发行结果；
  • Workflow job，用于在晋级 CI 的单个作业失败时提前写回失败通知并启动排查；
  • Check suite、Check run 和 Status，用于触发 CI 与可合并性刷新。

如果不需要在 Clowld Space 中显示 CI，可以不授予 Checks 和 Commit statuses 权限，也不订阅对应事件。但 Contents 仍然必须授予——缺少它时整个快照查询会直接失败，PR 卡片连合并状态也会一起消失。

不订阅 Workflow job（或未授予 Actions 权限）不影响其他功能：晋级失败通知退回整轮 Promotion Gate 完成后的既有行为，只是失去作业级的提前告警。

这里需要的是 Webhook secret，不是 OAuth Client secret。两边填写的 Webhook secret 不一致时，GitHub delivery 会返回 401 invalid signature。

2. 配置环境变量

从 App 的公开地址取得 slug。例如 https://github.com/apps/clowld-acme 的 slug 是 clowld-acme。

GITHUB_APP_SLUG=clowld-acme
GITHUB_WEBHOOK_SECRET=<创建 App 时填写的 webhook secret>
FRONTEND_ORIGIN=https://clowld.example.com

GITHUB_APP_SLUG 和 GITHUB_WEBHOOK_SECRET 缺少任意一个时，连接按钮会被禁用，webhook 接口也会拒绝处理事件。

下面两个变量是 PR 卡片显示 CI 状态与可合并性的必要条件——Clowld Space 用它们以 App 身份鉴权并拉取快照：

GITHUB_APP_ID=<GitHub App 的数字 ID>
GITHUB_APP_PRIVATE_KEY=<完整 PEM 私钥，保留 BEGIN/END 行和换行>

私钥在 GitHub App 的 Private keys → Generate a private key 中生成。不配置时集成会平稳降级：PR 照常镜像，任务照常自动关联并在合并后转为已完成，只是 PR 卡片不显示 CI 或合并状态。

3. 更新数据库并连接

升级已有部署时，先执行常规数据库迁移：

make migrate-up

重启 API 服务，再到 设置 → 代码 完成连接。

常见问题

  • 连接按钮不可用：检查 GITHUB_APP_SLUG 和 GITHUB_WEBHOOK_SECRET 是否已进入 API 进程。
  • Webhook 返回 401：确认 GitHub App 与 API 使用同一个 Webhook secret，然后在 GitHub 的 Recent Deliveries 中重新投递。
  • PR 没有关联：检查仓库是否在 App 授权范围内、自动关联是否开启、编号是否属于当前工作区，以及是否有人把它从任务上移除过。
  • 正文写了编号但没关联：改用 Closes CS-123，或把编号放到分支名、PR 标题中，或者手动关联。
  • 没有 CI 状态：确认 GITHUB_APP_ID 和 GITHUB_APP_PRIVATE_KEY 已配置，App 具有 Contents、Checks 与 Commit statuses 的只读权限并订阅了对应事件。缺少 Contents 会让整个快照失败，PR 卡片既没有 CI 也没有合并状态。给已安装的 App 补加权限后，还需要各 installation 的所有者在 GitHub 上批准才会生效。
  • PR 列表下方显示目标状态与仍待处理的 PR。缺少关闭语句、工作区选择不改变、任务已到达目标或已结束时，不显示流转提示。

接下来

Telegram Bot 接入

把 Clowld Space 智能体接入你自己的 Telegram Bot，支持私聊、群聊 @、forum topic 和 /issue。

GitHub 交付与失败恢复

区分开发交付、晋级、候选构建和正式发行的结果。

本页目录

连接 GitHub功能开关让 PR 关联到任务在任务中查看 PRPR 合并后转为已完成的条件多个工作区断开连接自托管配置1. 创建 GitHub App2. 配置环境变量3. 更新数据库并连接常见问题接下来