PR 自动联动 Issue:Its a Plan 的 GitHub / GitLab / Gitea Git 集成实战
PR 自动联动 Issue:Its a Plan 的 GitHub / GitLab / Gitea Git 集成实战
It's a Plan(itsaplan)是一款开源、可自托管的项目管理与 Issue 跟踪工具,定位为 Linear 和 Plane 的替代方案。它的 Git 集成功能让你在 GitHub、GitLab、Gitea、Forgejo、Bitbucket 上提交 Pull Request 时,自动关联并流转对应的 Issue——写代码的人不需要打开看板,合并 PR 的那一刻,Issue 状态就自动更新了。本文带你从零完成这套 PR 自动联动配置。
功能概览:一条 Webhook 串起代码库与看板
Its a Plan 的 Git 集成核心是一条入站 Webhook 接收端点(POST /webhooks/git/:webhookId)。所有已连接仓库的分支事件、PR 事件、CI 检查事件都通过这同一个端点送达,由服务端验证签名后统一处理。
它能帮你自动完成四件事:
- PR 自动关联 Issue:PR 标题或描述里写
Fixes PROJ-42,打开 PR 时自动建立关联; - 分支名自动关联:分支叫
feature/PROJ-42-payment,push 时自动关联,无需任何魔法词; - 合并自动改状态:PR 合并进默认分支时,关联的 Issue 自动移动到"已完成"列;
- 反向链接评论:新建立的关联会回写到 PR 评论区,附上 Issue 链接,方便评审人跳转查看。
快速启用:3 步完成 Its a Plan 仓库集成配置
第 1 步:打开项目的 Git 设置
进入项目 → 设置 → 仓库集成(Repository)标签页,打开"启用仓库集成"开关。开启后,页面会生成两个关键凭据:
- 请求地址(Payload URL):形如
https://<你的域名>/webhooks/git/<webhookId>,供仓库平台投递事件; - Webhook 密钥(Secret):以
whs_开头的 HMAC 签名密钥,服务端按项目加密存储。
对应的设置页源码见 SettingsGit.tsx。
第 2 步:选择连接方式
方式 A:平台授权(推荐)。在"代码托管平台连接"区域,输入对应平台的访问令牌后选择仓库,Its a Plan 会自动为你创建并配置好 Webhook,无需手工填写任何事件类型:
- GitHub:使用对目标仓库具备 Metadata 读取、Webhooks 写入、Pull requests 写入权限的 fine-grained token;
- GitLab:使用具有 API 权限的 personal access token(列表只显示你有 Maintainer 或 Owner 权限的项目);
- Gitea / Forgejo / Bitbucket:使用能够管理目标仓库 webhook 的访问令牌。
每次最多可连接 50 个仓库,令牌加密存储,API 绝不会回显。
方式 B:手动添加 Webhook。展开"手动连接仓库",按平台标签页照做即可:
| 平台 | 需要启用的事件 |
|---|---|
| GitHub | Pull requests、Check runs、分支创建/删除 |
| GitLab | Merge request、Pipeline、Push |
| Gitea / Forgejo | Pull request、分支创建/删除 |
| Bitbucket | Pull request、分支创建/删除 |
设置页还会直接给出可复制的命令行。例如 GitHub 场景下,一条 gh api 命令即可建好 webhook(见 githubCommand.ts):
gh api repos/<owner>/<repo>/hooks \
-f name=web -F active=true -f 'events[]=pull_request' -f 'events[]=check_run' \
-f 'events[]=create' -f 'events[]=delete' \
-f 'config[url]=https://你的域名/webhooks/git/你的webhookId' \
-f 'config[content_type]=json' -f 'config[secret]=whs_你的密钥'
第 3 步:验证连接
推送一次任意事件后,设置页的"仓库"列表会显示最近向该项目发送事件的仓库及其时间,说明链路已通。
Magic Words 实战:PR 标题里该写什么
Its a Plan 沿用了 Linear 风格的魔法词语法,解析逻辑位于 magic-words.ts。规则很简单:
| 词类 | 示例 | 效果 |
|---|---|---|
| 关闭词 | fixes、closes、resolves、completes、implements |
PR 合并到默认分支时,Issue 自动移到已完成状态 |
| 引用词 | ref、refs、relates to、part of |
仅建立关联,不改变 Issue 状态 |
| 跳过词 | skip、ignore |
忽略该编号,并删除已有关联 |
一个 PR 可以关联多个 Issue,用逗号或 "and" 分隔:
Fixes PROJ-42
Closes PROJ-1, PROJ-2 and PROJ-3
Ref PROJ-99
Skip PROJ-7
💡 注意:关闭动作仅在 PR 合并到仓库默认分支时触发,合并到 feature 分支不会改变 Issue 状态。
分支名约定:不写魔法词也能关联
其实大多数团队更习惯用分支名带编号。Its a Plan 会解析源分支名开头的编号——feature/PROJ-42-payment、bugfix-PROJ-42 这类命名都会自动建立"开发关联",PR 打开后关联自动升级为 PR 关联。解析实现见 handler.ts。
拉取请求自动化:合并即改状态
在"拉取请求自动化"卡片中(源码见 GitAutomationsCard.tsx),你可以配置三条规则,全部即时生效、无需保存:
- 关联的 PR 合并时:选择目标列,Issue 合并后自动移入;留空则默认移到项目的"第一个已完成状态"列;
- 关联的 PR 打开时:可选把仍处于 Backlog / 未开始状态的 Issue 移到指定列(进行中和已关闭的不动),留空则不执行操作;
- 发布反向链接评论:默认开启,通过已连接的平台账号在 PR 中评论 Issue 链接。
所有状态变更都走与手动改状态相同的通道,因此状态活动记录、出站 Webhook、子任务自动化和成员通知都会照常触发。
安全机制:签名验证与防重放
- HMAC 签名:每个平台按自身方式签名 payload(如 GitHub 的
X-Hub-Signature-256),服务端用项目的 Secret 逐字节验签,签名不对直接返回401 Invalid signature; - 防重放:平台每次投递带唯一 delivery id,重复投递(重试)会被识别为 duplicate 并跳过,不会重复移动 Issue;
- 密钥轮换:设置页可随时"重新生成"Secret,旧密钥立即失效。
接收端实现见 webhook.ts,各平台适配器与验签逻辑见 providers.ts。
相关文档与源码
- 自托管部署指南:docs/self-hosting.md
- 快速体验指南:docs/railway.md
- Git 集成后端模块:apps/api/src/modules/git/
- 前端设置页组件:apps/web/src/features/settings/components/git/
- 中文界面文案(Git 部分):apps/web/messages/zh-CN/settings.json
按上面的流程配置完成后,你的团队就拥有了"代码合并即进度更新"的体验:Issue 状态永远和代码库保持同步,而没有人需要手动去点看板。

