SuperAPI AI 工具集

Linear VCS Bridge (GitHub and Harness Code)

编程与开发

查看项目

更新于 10-16 06:57

技能介绍

用途

Linear VCS Bridge 用于在 Linear 议题与 Git 托管平台之间实现或调试双向同步,涉及分支、拉取请求、评审和部署。它面向需要把 Linear 与 GitHub 或 Harness Code 打通的团队,尤其是使用 Harness Code 的场景——Linear 自带的代码评审产品 Diffs 只集成 GitHub,Harness Code 用户无法在 Linear 中获得评审界面。

主要能力

  • 提供商抽象:一个与提供商无关的行为层,加上每个托管平台的薄适配器,只覆盖真正有差异的部分。
  • 议题键提取:extractIssueKeys(text) 严格匹配大写,避免在自由文本中误匹配 utf-8、sha-256、covid-19 等;extractClosingKeys(text) 识别 fixes / closes / resolves 等关键词后的键,键本身大小写不敏感。
  • 分支命名:branchNameForIssue 生成与 Linear 自身“复制 git 分支名”动作相同形状的分支名,使 Linear 的自动关联无需桥接帮助即可识别。
  • 幂等处理:两个托管平台都会重试投递,处理器必须幂等,按投递 ID(Linear-Delivery、X-GitHub-Delivery、X-Harness-Delivery)去重,无 ID 时选择放行(fail open)。
  • 恢复:不构建投递重放,而是构建对账(reconcile),比较 Linear 状态与 VCS 状态并修复差异。

使用方式

实现位于 lib/vcs/ 目录:provider.mjs(契约)、github.mjs、harness.mjs、index.mjs(选择)。命令入口为 commands/sync.md,流向 VcsProvider 契约,再分派到 GitHubProvider 或 HarnessProvider。在把任何内容路由到 /linear:review 之前,先检查 provider.supportsLinearDiffs;在 Harness 上,改为把评审状态镜像为议题评论,并用 attachToIssue 附加 PR。

签名验证:Linear 使用 Linear-Signature 头,Harness 使用 X-Harness-Signature 头,两者均为裸十六进制;GitHub 使用 X-Hub-Signature-256,带 sha256= 前缀。从 GitHub 集成复制到 Linear 处理器的代码会拒绝一切,反之亦然。始终对原始请求体验签,对重新序列化的对象验签会因键顺序和 Unicode 转义而间歇性失败。

适用场景

  • 在 Linear 议题与 GitHub 或 Harness Code 之间同步分支、PR、评审和部署状态。
  • 需要让合并事件触发议题状态迁移(仅关闭关键词触发 Done)。
  • 需要在大规模工作区中对账修复漂移。

限制与注意事项

  • 只有关闭关键词应触发 Done 迁移;PR 正文中裸的 ENG-2 只是引用,不是关闭承诺。
  • Linear 可能已自行迁移议题:"On git branch copy, move issue to a started status" 是每用户设置,添加桥接规则前先检查是否重复。
  • 去重集合需同时按大小和 TTL 设界,否则会无限增长。
  • 速率限制:Linear(API 密钥)2,500 请求/小时 + 300 万复杂度/小时;Linear(OAuth)5,000 请求/小时 + 200 万复杂度/小时;GitHub 认证 REST 5,000 请求/小时;Harness 按账户,遇 429 退避。Linear 单次查询上限 10,000 复杂度点,大工作区对账会触及此限制,需分页并读取 X-Complexity 响应头。

参考

  • Linear webhooks: https://linear.app/developers/webhooks
  • Linear Diffs: https://linear.app/docs/diffs
  • Harness API: https://apidocs.harness.io