Skip to content
SprintLoop / docs

GitHub

GitHub 是多数工作区最先接入的集成。SprintLoop GitHub App 让一条 lane 能 push 分支、开 PR、发状态评论，以及把 CI 信号 ingest 回 lane 的审计台账。没装这个 app，lane 对 GitHub 是只读的；装了之后，它们是完整的协作者。

本页覆盖安装、scope、仓库连接、分支保护、webhook 流，以及最常见的坑。

安装 app

在 SprintLoop 内：Settings → Integrations → GitHub → Install the GitHub App。 你会被重定向到 GitHub 的 app 安装流程。

GitHub 会让你选：

  1. 账号或 org。 选拥有目标仓库的那一方。你可以把 app 装到多个 org 上，并在之间切换。
  2. 仓库。 想把 org 下所有仓库都接进来就选 All repositories，想挑子集就选 Only select repositories。推荐 “select” 路径——一旦某条 lane 跑歪，可以把爆炸半径限制住。

安装完成后你会回到 SprintLoop，每个已连接仓库一行绿色状态。app 在后台抓默认分支、分支保护规则和 CI 配置；通常 5–15 秒。

所需 scope

安装时 app 申请以下权限：

Scope用途
contents: writepush lane 分支、写 commit
pull_requests: write开 PR、发状态评论
checks: read把 CI 状态 ingest 进 lane 审计台账
members: read展示来自你团队的 PR reviewer 候选
metadata: read读仓库设置（默认分支、分支保护）

它不申请：

  • secrets —— SprintLoop 不读不写你的仓库 secret。
  • packages —— 不访问 GitHub Packages。
  • admin:org —— 不访问 org admin endpoint。
  • delete:repo —— 没有破坏性权限。

如果你的安全团队要审计，manifest 公开在 https://github.com/apps/sprintloop，scope 在 app 的公开页面上可见。

仓库连接

一个仓库要同时满足两个条件才算”已连接”：app 装在了它上面，并且工作区在 Settings → Integrations → GitHub → Repos 把它列了出来。首次安装会自动填这份列表；之后可以在不卸载 app 的情况下断开某个仓库。

每个已连接仓库都会拿到：

  • 默认分支（从 GitHub 自动检测）。
  • 一个作用域 policy（默认：lane 可以 claim 该仓库下任何路径）。
  • 一个 CI ingest 设置（默认：checks: all）。
  • 一个可选的 PR template 覆盖。

连接是按工作区计的。同一个仓库可以同时连到两个 SprintLoop 工作区——OSS 项目把 dev 工作区和 security 工作区分开时很有用。来自不同工作区、针对同一仓库的 lane 不共享作用域 claim；冲突在 GitHub 侧的 PR-merge 时刻解决。

lane 开 PR 时发生的事

完整流程：

  1. owner 批准 lane。
  2. SprintLoop 把 lane 的签名 commit push 到已连接仓库上一个名为 sprintloop/<workspace-handle>/<lane-id> 的分支。
  3. SprintLoop 通过 GitHub API 开一个 PR。PR 标题是 lane 标题；PR 正文包含 brief、所用 harness、模型版本、Review Committee 判定，以及指向该 lane 审计页的链接。
  4. GitHub 触发状态检查和任何分支保护要求的 reviewer。
  5. SprintLoop 把检查结果 ingest 回 lane 的链（签名条目——每条 CI 状态都可审计）。
  6. PR 在 GitHub 上被 merge（由你或队友），SprintLoop 收到 pull_request.closed webhook，把该 lane 标为 merged，并戳进 federation root。

PR 描述默认很啰嗦。如果团队偏好简短 PR，在 Settings → Integrations → GitHub → PR template 设一个模板。模板支持与 lane brief 相同的 Liquid 风变量（{{lane.title}}、{{lane.harness}} 等）。

分支保护

如果你的仓库有要求 N 次 approval、要求 CI 绿、或限制 force push 的分支保护，SprintLoop 全都尊重。lane 的 sign-off 是内部的——它是工作区所有者审过这条 lane 的声明——不是一次 GitHub review。你的分支保护规则在 GitHub 侧仍然生效。

一个常见模式：分支保护在 SprintLoop sign-off 之上再要求一次外部 GitHub review。团队拿到外部一双眼睛的安全感；lane 的审计链则记录 SprintLoop reviewer agent 和工作区所有者所看到的一切。

如果分支保护要求一项 lane 无法满足的状态检查（比如只在受保护路径变更时才跑的自定义检查），你会在 lane 页上看到一条黄色横幅指明缺失的检查。merge 会失败，直到该检查被满足或规则被修改。

app 订阅的 webhook

app 订阅：

  • pull_request —— 跟踪 PR 的 merge / close。
  • push —— 刷新 Context Engine 的仓库结构图。
  • check_run 与 check_suite —— ingest CI 状态。
  • installation 与 installation_repositories —— 保持已连接仓库列表同步。
  • workflow_run —— 把 Actions run 归到触发它的 lane 上。

Webhook 发送至 https://api.sprintloop.ai/integrations/github/webhook。该端点在每次请求时校验 GitHub 签名头，并在 <50ms 内返回 200（工作进队列，不在线内处理）。如果 GitHub 在你 org 的设置里报持续性 webhook 失败，几乎总是一次性问题——app 会自动重试、自愈——但持续 24 小时失败率超过 1% 时请联系 support。

常见坑

“我的 lane 已经 push 了，但没有 PR 开出来。” 检查 lane 分支是否对着正确的 base 被 push。如果你的仓库默认分支是 develop（不是 main），lane 在不按 per-dispatch 覆盖的情况下会用 develop 作 base。如果同一分支上已经存在 PR，PR 创建会失败（我们不重复开）。

“GitHub 上 CI 已绿，但 lane 显示 pending。” 检查 ingest 依赖 check_suite.completed webhook。某些 CI provider 在视觉上的绿勾出来之后还要 30–60 秒才发这条。如果 5 分钟后仍是 pending，说明 webhook 没到我们这——在 GitHub 上重新触发 suite，或在 lane 页点 Re-sync CI。

“我想改用 GitLab 或 Bitbucket。” GitLab 通过同样形状的集成支持——见 Integrations index。Bitbucket 在 2026 Q3 的 roadmap 上。

“app 每来一个新仓库都要我重新授权。” GitHub App 的权限授予是按 org 计的，新仓库需要在 app 的 Configure 页面手动添加。我们故意不自动 claim 新建仓库——opt-in 是一个有意识的动作。