Issue 追踪、代码回链与关闭语义手册
Issue 追踪解决的是工作项与代码事实的连接。GitHub 和 GitLab 的仓库、权限与平台部署由各自产品主文负责；这里关注两者都存在的任务语义：模板怎样收集证据，标签与里程碑怎样分工，关闭关键字何时生效，Board 为什么只能是查询视图。
Issue 身份比标题稳定
启用入口可以是仓库原生 Issues，也可以是组织级模板和表单。Issue 通过仓库命名空间与编号或不可变 URL 定位，标题只供人阅读。跨仓库引用必须携带完整命名空间，自动化不能拿标题匹配目标。
模板收集观察、最小复现、期望、环境和验收证据。字段只保留会被分流、查询或验证的内容；强迫作者填写无人消费的段落，会增加伪造信息和复制粘贴。
标签、里程碑与 Board 分工
标签表达正交分类，例如类型、领域和风险；里程碑聚合同一交付结果；assignee 表达当前 owner。Board 根据这些字段查询和投影，拖动卡片只有在明确自动化映射到字段或状态时才改变事实。
Issue：稳定工作项
Label：分类与风险
Milestone：共同交付结果
Board：查询视图配置影响通过少量测试 Issue 验证。创建、分流、关联、关闭和重开都要产生可查询事件，不能只看列位置变化。
代码引用与关闭事件
分支、提交和 PR/MR 正文引用 Issue，合并结果再触发关闭。GitHub 和 GitLab 的关键字、目标分支与跨项目语法存在差异，因此实际规则必须在目标实例实验。默认分支、合并策略和权限共同决定事件是否发生。
Issue -> branch -> commit -> PR/MR -> merge event
-> build -> deploy -> acceptance / reopen正向验证让一个测试修复从 Issue 走到合并，并确认时间线记录关联 actor 与提交。反例把目标改为非默认分支或使用错误命名空间，预期 Issue 保持打开。合并成功不等于已经部署验收，关闭后仍要回写发布或验收证据。
API 自动化保持幂等
自动化使用应用身份和最小仓库权限，事件键包含平台、仓库、Issue 与事件 ID。重复 webhook 不重复评论或改变状态，乱序事件通过对象版本或时间线判断。失败进入重试队列，并保留人工修正入口。
权限按读取、创建、编辑、关闭、管理标签和管理模板拆分。外部贡献者不应自动取得内部里程碑与敏感附件。Token 从 secret 管理注入，日志不记录正文、客户数据和凭证。
故障证据和项目接入
Issue 未关闭时依次检查关键字、目标分支、合并方式、跨仓库命名空间和执行者权限。关联出现但状态错误，则查看平台时间线与 API 响应。项目接入先建立一条规则并验证，再扩展标签同步和跨系统回写。
通知平台只消费事件摘要，不能成为状态事实源。聊天中的“已处理”必须回到 Issue、代码或发布对象。容量治理关注长期无 owner、重复标签、机器人噪声和关闭后反复重开的工作项。
归档、迁移与恢复
归档仓库前停止自动写入，导出 Issue、评论、标签、里程碑、附件和关系。迁移时保留原始 ID 映射与旧 URL 重定向，抽样验证跨仓库引用和权限。只搬标题与正文会丢失时间线和交付证据。
错误自动化先停规则，再根据事件日志回滚批量修改。长期 owner 定期检查模板、标签、关闭规则和应用权限。Issue 系统可信的标准不是关闭率，而是任何关闭都能解释由哪个事件、代码和验收证据触发。