GitHub 与 GitLab Issues 项目追踪、自动关联与治理手册

高谷深陵大约 31 分钟约 9306 字

Issue 到代码合并回链参考图区分普通引用与自动关单，显式验证默认分支、跨仓库语法、仓库开关、权限和发布验收。高清原图

合并成功，为什么工单反而失真了

支付回调偶尔会重复入账。值班开发创建了一个 Issue，修复 PR 的描述里写着 Fixes #86。代码通过评审并合入，Issue 随即自动关闭，看板也把卡片移动到 Done。几小时后，测试发现修复只覆盖了同步回调，异步补偿仍会重复执行。更麻烦的是，#86 实际属于当前 SDK 仓库，而最初报告保存在另一个服务仓库；团队看到的是一条整洁的绿色链路，链路连接的却不是同一个问题。

这类事故不是“大家没有及时更新状态”，而是协作对象没有建模。Issue 的关闭状态、看板列、代码合并、发布完成和业务验收是五种事实。closing keyword 只能证明某次提交进入了约定分支，不能证明修复已经发布，更不能证明业务现象消失。只要团队把这些事实压成一个 Done，自动化越顺畅，错误就传播得越快。

GitHub Issues 和 GitLab Issues 都能把问题、讨论、代码变更与计划组织在代码平台附近，但两者的对象归属、权限、模板、看板和迁移行为并不完全相同。先把对象关系弄清楚，再启用自动关单，才能让 Issue -> Commit -> PR/MR -> Merge -> Verify 成为证据链，而不是一串看起来相关的链接。

一张卡片背后有六类对象

最小协作链路至少有六类对象：

Issue 保存问题身份、当前状态、讨论和验收证据。Label 表达可组合的分类维度，例如类型、优先级、责任域和流转阶段。Milestone 聚合一组需要共同交付的 Issue 与 PR/MR，表达一次目标或交付批次。

Project 或 Issue Board 是对象视图，通过字段、过滤器和列展示工作，不应成为第二份问题数据库。Commit 与 PR/MR 保存实现证据，引用 Issue，但不替代 Issue 中的问题描述和验收结论。Timeline、system note、webhook 与 audit event 保存不同层次的变更证据。

在 GitHub 中，Issue 属于 repository；Label 与 Milestone 也首先是 repository 对象。GitHub Projects 位于用户或组织层，可以同时容纳多个仓库的 Issue、PR 和 draft issue，并给项目项附加自定义字段。项目字段与 Issue 字段是两个层次：项目里的 Status=Done 不等于 Issue 已关闭，draft issue 也还不是某个仓库里的正式 Issue。GitHub Projects 的对象说明明确把 table、board、roadmap、custom field 和自动化组织在同一个项目模型中。

在 GitLab 中，Issue 始终关联一个 project；project label 只服务当前项目，group label 可服务该组及其子组中的项目；Milestone 既可以属于 project，也可以属于 group。Issue Board 是 Issue 的视图，列可以由 label、assignee、milestone、iteration 或 status 驱动。把卡片拖进 label 列，会修改 Issue 的 label，而不只是改变画面位置。GitLab Issue Board 文档给出了列类型、拖动副作用和 group board 的聚合方式。

这一区别会直接影响自动化。机器人若把 GitHub Project 自定义字段当成 Issue 状态，可能关闭仍在调查的问题；机器人若把 GitLab Board 当作独立卡片系统，可能重复写入实际已经由 label 表达的状态。

图中最重要的不是自动关闭，而是关闭后仍有一条业务验证分支。团队可以让代码合并触发 state=closed，但应使用独立的 verification:passed、Project 字段或验收评论表达最终结果。高风险修复甚至可以禁用自动关闭，只保留关联，由责任人确认发布和回归证据后关单。

先启用一个隔离的协作入口

不要在生产仓库里第一次试模板和自动关单。创建一个无业务数据的私有实验仓库或项目，默认分支命名为 main，准备普通报告者、维护者和机器人三种身份。普通报告者验证能否提交而不能改治理配置；维护者验证 label、milestone、模板和转移；机器人只验证 API 所需动作。

GitHub 仓库管理员在 Settings -> General -> Features 启用 Issues，也可以把创建入口限制为 collaborators。关闭 Issues 不会删除旧数据，重新启用后原 Issue 仍可见，具体行为见仓库 Issues 开关。GitLab 在 Settings -> General -> Visibility, project features, permissions 中启用 Work items；关闭该能力还会影响 Issue Boards，并可能连带影响 Label 与 Milestone 的可用入口，操作前应查看项目功能依赖。

浏览器足以完成第一次实验。需要把流程接入脚本时，再安装 GitHub CLI 或 GitLab CLI，并先确认实际连接的主机与身份：

gh --version
gh auth status

glab --version
glab auth status

预期输出应包含 CLI 版本、目标主机和已认证账号。command not found 表示 CLI 尚未安装或不在 PATH；认证状态指向错误主机时，不要继续创建 Issue，因为同名仓库很容易让实验落到错误实例。企业版或自建 GitLab 还要确认代理、DNS 和企业 CA，证书失败不能通过永久关闭 TLS 校验来“修好”。

首次启用后，用 UI 创建标题为 LAB: duplicate callback 的 Issue，再用 API 读取。此时只验证对象可见性，不授予机器人写权限。GitHub CLI 可以这样探测：

export GH_REPO='your-org/review-lab'

gh issue list \
  --repo "$GH_REPO" \
  --state open \
  --search 'LAB: duplicate callback' \
  --json number,title,state,url

GitLab REST API 可以这样探测：

export GITLAB_BASE_URL='https://gitlab.example.com'
export GITLAB_PROJECT_ID='<numeric-project-id>'
export GITLAB_TOKEN='<inject-from-secret-store>'

curl --fail-with-body --silent --show-error \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --get "$GITLAB_BASE_URL/api/v4/projects/$GITLAB_PROJECT_ID/issues" \
  --data-urlencode 'state=opened' \
  --data-urlencode 'search=LAB: duplicate callback'

成功响应至少应出现稳定编号、标题、状态和 URL。GitHub 常用仓库内 number，GitLab 同时有全局 id 与项目内 iid；日志和数据库应保存平台、主机、仓库或项目 ID、Issue ID 与 URL，不能只保存一个 #86。

Label 是正交维度，不是彩色句子

一套失控的标签通常长这样：bug、urgent、important、backend、doing、almost-done、waiting。它们混合类型、优先级、领域和状态，机器人无法判断哪些可以共存，Board 也无法形成稳定列。

更可维护的起点是给标签定义命名维度：

type:bug          问题类型
priority:p1       处理优先级
area:payment      责任域
workflow:ready    当前协作阶段
verification:need 是否还缺业务验收

同一维度通常只能保留一个值，跨维度可以组合。GitLab 还提供 scoped label 语义，但能力与方案可能变化；希望在 GitHub、GitLab 和外部系统间迁移时，前缀命名加自动化互斥检查更容易保持一致。GitHub Label 是仓库级对象；GitLab 的 project、group 和 instance label 有不同传播层次，见GitLab Labels。

标签描述要写“何时添加、由谁移除、与哪些标签互斥”，颜色只帮助扫描。priority:p1 不能由提交者随手选择，应有故障影响或响应规则；workflow:done 也不能和 Issue closed 重复表达同一个事实，否则迟早出现“closed + workflow:doing”。

Milestone 绑定共同结果，不替代排期系统

Milestone 适合聚合“必须共同完成才能交付”的 Issue 和 PR/MR，例如一次协议升级或一次客户端兼容发布。它不适合给每个零散问题设置截止日期，也不应该同时承担季度目标、迭代、发布版本和个人待办四种语义。

GitHub Milestone 属于仓库。跨仓库交付若只依赖同名 Milestone，会得到多个彼此独立的对象；可在组织级 Project 中设置统一 Release train 字段，再保留各仓库 Milestone 作为本地交付容器。GitLab group milestone 可以分配给组内项目的 Issue 与 MR，更适合组级交付聚合；project milestone 则保持本地责任。GitLab Milestones说明了两种归属和与 Issue、MR 的关联。

进度百分比通常由关闭数量计算，无法表达 Issue 权重、验收风险和未创建工作。架构评审不要把“Milestone 已完成大部分”直接当成发布置信度。真正的发布判断还要看阻塞关系、未验收项、回滚准备和发布证据。

模板要收集诊断证据，而不是制造填空劳动

好的缺陷模板要求报告者给出可观察事实：环境或版本、最小复现、实际结果、预期结果、影响、脱敏日志和回归判据。不要要求报告者猜根因、实现方案或内部 owner；这些字段会制造错误分类。

GitHub Issue Forms 位于默认分支的 .github/ISSUE_TEMPLATE/*.yml。下面的表单把必填项限制在能够决定是否可复现的字段：

name: Bug report
description: Report a reproducible product defect
title: "[Bug] "
labels:
  - "type:bug"
  - "workflow:triage"
body:
  - type: dropdown
    id: environment
    attributes:
      label: Environment
      options:
        - local
        - test
        - production
    validations:
      required: true
  - type: textarea
    id: reproduction
    attributes:
      label: Minimal reproduction
      description: Use synthetic data and remove credentials or customer identifiers.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected result
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: Actual result and evidence
      render: shell
    validations:
      required: true
  - type: checkboxes
    id: sensitive-data
    attributes:
      label: Data handling
      options:
        - label: Logs and attachments are sanitized
          required: true

模板只有进入默认分支后才会出现在创建入口。.github/ISSUE_TEMPLATE/config.yml 可以关闭普通贡献者的 blank issue，并把安全报告或支持请求导向受控入口；维护者仍可能看到 blank issue 选项。Issue Forms 仍可能处于预览或继续演进，采用前应检查GitHub Issue Template 配置和表单 schema。

GitLab 的 Issue description template 是默认分支中 .gitlab/issue_templates/*.md。它是 Markdown 内容复制，不是强类型表单；可以在模板末尾放 quick action，但动作只会在提交者有相应权限时执行：

## Observed behavior

<!-- Describe the externally visible symptom. -->

## Minimal reproduction

<!-- Use synthetic data. Remove tokens, customer data and internal hosts. -->

## Expected behavior

## Evidence

<!-- Paste sanitized logs or a stable artifact link. -->

## Acceptance evidence

- [ ] Regression test fails before the fix
- [ ] Regression test passes after the fix
- [ ] Rollback path is known

/label ~"type:bug" ~"workflow:triage"

Default.md、项目设置、group template repository 之间存在优先级，部分集中模板能力还受产品方案影响。团队升级或改变采购方案时，应在目标实例创建一次 Issue，确认实际采用了哪个模板，而不是只检查仓库文件存在。GitLab Description Templates列出了目录、继承顺序、默认模板和 quick action 行为。

模板发布前做一次反向测试：删除一个必填字段或写入不存在的默认 label。GitHub 表单 schema 错误可能让模板不出现在 chooser；GitLab quick action 权限不足或对象不存在时，正文仍可能创建成功，但 label、assignee 或 milestone 没有按预期设置。验证时必须同时检查 Issue 正文和元数据，不能把“创建成功”当成模板全部生效。

Board 是查询视图，不是事实源

Board 最常见的失真来自两套状态并存：Issue 已关闭，但 Project 的 Status 仍是 In progress；或者卡片拖到 Done，却没有合并、发布与验收证据。避免失真的关键是为每个字段指定唯一写入者和状态映射。

一种可执行的映射是：

Issue opened                   -> lifecycle=open
PR/MR opened and linked        -> delivery=implementing
PR/MR merged to default branch -> delivery=merged
deployment evidence attached   -> delivery=deployed
acceptance evidence passed     -> verification=passed
Issue closed                   -> lifecycle=closed

GitHub Project 的自定义字段适合表达 delivery 和 verification，Issue state 继续表达 lifecycle。GitLab 可以用互斥 workflow label、status 或受控字段表达流转；拖卡片会改底层属性，因此机器人和人工不能同时抢写同一维度。

Board 查询要保留三个异常视图：已关闭但未验收、已合并但未关闭、长时间无 owner。它们比一张“所有卡片都在 Done”的展示板更有治理价值。自动归档只从活跃视图移走项目项，不等于删除 Issue；GitHub Project 的归档项仍保留自定义字段并可恢复，见Project 自动归档。

正向实验：让修复链路自动闭合

下面的实验在隔离仓库中创建 Label、Milestone 和 Issue，再让 PR 合入默认分支触发自动关闭。命令使用 Bash 与 GitHub CLI；仓库需要 Issues 写权限、推送实验分支的权限和合并 PR 的权限。

先创建元数据。--force 让重复执行更新已有 Label，而不是留下同名变体：

export GH_REPO='your-org/review-lab'

gh label create 'type:bug' \
  --repo "$GH_REPO" \
  --color 'B60205' \
  --description 'A reproducible product defect' \
  --force

MILESTONE_NUMBER="$(
  gh api --method POST "repos/$GH_REPO/milestones" \
    -f title='review-lab-release' \
    -f description='Disposable milestone for issue-link verification' \
    --jq '.number'
)"

ISSUE_NUMBER="$(
  gh api --method POST "repos/$GH_REPO/issues" \
    -f title='LAB: duplicate callback' \
    -f body='Reproduce with synthetic callback ID LAB-42. Acceptance: one ledger entry.' \
    -f 'labels[]=type:bug' \
    -F milestone="$MILESTONE_NUMBER" \
    --jq '.number'
)"

gh issue view "$ISSUE_NUMBER" \
  --repo "$GH_REPO" \
  --json number,title,state,labels,milestone,url

预期 Issue 为 OPEN，包含 type:bug 和 review-lab-release。422 Unprocessable Entity 通常表示 Label 或 Milestone 不存在、字段不合法或身份不能执行该动作；404 既可能是路径错误，也可能是私有仓库对当前身份不可见。

在实验仓库工作树中创建一个无业务影响的变更，让 PR 描述使用完整引用：

git switch -c "lab/fix-$ISSUE_NUMBER"
printf 'callback deduplication lab\n' > review-lab.txt
git add review-lab.txt
git commit -m "test: add callback deduplication marker"
git push -u origin "lab/fix-$ISSUE_NUMBER"

PR_URL="$(
  gh pr create \
    --repo "$GH_REPO" \
    --base main \
    --head "lab/fix-$ISSUE_NUMBER" \
    --title 'LAB: verify issue closing link' \
    --body "Fixes $GH_REPO#$ISSUE_NUMBER"
)"

gh pr view "$PR_URL" --repo "$GH_REPO" --json url,state,baseRefName,closingIssuesReferences
gh pr merge "$PR_URL" --repo "$GH_REPO" --merge --delete-branch
gh issue view "$ISSUE_NUMBER" --repo "$GH_REPO" --json state,closedAt,url

PR 创建后，closingIssuesReferences 应包含目标 Issue；合入 main 后，Issue 应变为 CLOSED，timeline 中出现关联与关闭事件。GitHub 的 closing keyword 只在 PR 目标是仓库默认分支时建立自动关闭关系；同仓库可以写 Fixes #86，跨仓库必须写 Fixes owner/repository#86。仓库管理员还可以关闭“合并关联 PR 后自动关单”，此时链接仍是交付证据，但合并不再改变 Issue state。支持的词与默认分支条件见PR 与 Issue 关联规则，开关行为见GitHub 自动关单设置。

Commit message 也能使用 closing keyword。Commit 进入默认分支时可以关闭 Issue，但包含该 Commit 的 PR 不会因此显示为 linked pull request。需要评审界面明确展示交付关系时，把 closing reference 放在 PR 描述中，Commit 只放普通引用或可搜索的 Issue ID。

反向实验：合并了，Issue 仍然保持打开

先重新打开实验 Issue，并创建一个非默认目标分支：

gh issue reopen "$ISSUE_NUMBER" --repo "$GH_REPO"

git switch main
git pull --ff-only
git switch -c lab-staging
git push -u origin lab-staging

git switch -c "lab/non-default-$ISSUE_NUMBER"
printf 'non-default branch experiment\n' >> review-lab.txt
git add review-lab.txt
git commit -m "test: target a non-default branch"
git push -u origin "lab/non-default-$ISSUE_NUMBER"

NEGATIVE_PR_URL="$(
  gh pr create \
    --repo "$GH_REPO" \
    --base lab-staging \
    --head "lab/non-default-$ISSUE_NUMBER" \
    --title 'LAB: non-default closing experiment' \
    --body "Fixes $GH_REPO#$ISSUE_NUMBER"
)"

gh pr merge "$NEGATIVE_PR_URL" --repo "$GH_REPO" --merge --delete-branch
gh issue view "$ISSUE_NUMBER" --repo "$GH_REPO" --json state,url

预期 PR 成功合入 lab-staging，Issue 仍为 OPEN。在 GitHub 中，这种 PR 的 closing keyword 会被忽略，甚至不会建立 closing link。故障证据不是“机器人晚了”，而是 baseRefName 不等于默认分支。若 baseRefName 已是默认分支且 closingIssuesReferences 也正确，再检查目标仓库的自动关单开关；不要扩大 Token 权限，因为关单由平台在合并事件上执行。修复时先判断变更是否还会进入默认分支；如果会，创建或调整面向默认分支的 PR，如果不会，则保留普通关联并由 owner 按验收结果处理。

GitLab 的等价规则是：Commit 被推入项目默认分支，或 Commit/MR 合入默认分支后，匹配 closing pattern 的 Issue 才会自动关闭。Closes #4, #6, Related to #5 会关闭前两个，并只关联第三个；Self-Managed 管理员还可以修改 closing pattern，项目也可以关闭自动关单能力。GitLab 自动关闭规则应成为升级和迁移测试的一部分，不能假设每个实例都接受同一组词。

GitLab 上可用下面的最小读取验证关单结果：

export GITLAB_BASE_URL='https://gitlab.example.com'
export GITLAB_PROJECT_ID='<numeric-project-id>'
export GITLAB_ISSUE_IID='<issue-iid>'
export GITLAB_TOKEN='<inject-from-secret-store>'

curl --fail-with-body --silent --show-error \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_BASE_URL/api/v4/projects/$GITLAB_PROJECT_ID/issues/$GITLAB_ISSUE_IID"

预期 JSON 的 state 与 UI 一致，并能看到 references、labels、milestone 和 web_url。若 MR 已合入默认分支但 Issue 未关闭，依次检查：MR 描述或 Commit 正文是否真的匹配实例 closing pattern、引用是否指向正确项目、被引用 Issue 所属项目是否禁用自动关闭、执行合并的身份是否有权关闭目标 Issue，以及这是否是导入已有仓库后的首次 push 特例。GitLab 检查的是合并者的关单权限；公开项目里外部贡献者可以提交带 closing pattern 的内容，却不能借此绕过目标 Issue 的权限边界。

关联引用必须携带命名空间

#86 只在当前仓库或项目上下文中稳定。聊天、发布单、日志平台和跨仓库机器人离开上下文后，无法知道它指向哪里。团队应使用以下外部身份：

GitHub: github.example/your-org/review-lab#86
GitLab: gitlab.example/your-group/review-lab#86
Storage key: <platform>/<host>/<repository-or-project-id>/<issue-id>

展示给人时使用完整引用和 URL；存储给机器时使用不可因重命名而变化的资源 ID，并同时保存当前 URL。短编号只适合对象内部显示。

GitHub 跨仓库 closing reference 使用 owner/repo#number。Issue transfer 只允许在同一用户或组织拥有的仓库之间进行，调用者需要源与目标仓库的写权限，私有仓库 Issue 不能转移到公开仓库。评论和 assignee 会保留；Label 需在目标仓库按名称匹配，Milestone 需按名称与 due date 匹配，旧 URL 会重定向，细节见GitHub Issue transfer。转移前先同步元数据，否则 Issue 虽然移动成功，分类和交付归属已经丢失。

GitLab 的 related issue 是双向关系，可以跨 project，关系可表达 relates to、blocks 和 is blocked by。用户必须能访问两端，UI 才会展示完整关系；不同项目使用 group/project#86。需要跨项目依赖图时，使用结构化 linked issue，不要只在评论里粘 URL。GitLab Linked Issues同时说明了权限与可见性行为。

跨仓库项目追踪有两种稳定架构：

代码归属型：Issue 留在最接近实现 owner 的仓库，组织级 Project 或 group board 聚合视图。产品归属型：统一 tracker 保存用户问题，各代码仓库的 PR/MR 使用完整引用，tracker 保持 canonical issue。

不要在每个仓库复制同一 Issue。副本同步需要解决评论、关闭、权限、附件和编号冲突，最终会把一个问题变成多个互相争夺的事实源。确需向外部客户暴露支持入口时，公开 Issue 只保存脱敏摘要和状态，内部安全或客户数据留在受控工单中，两端用非敏感关联 ID 连接。

权限要按动作拆分

Issue 协作不要求所有参与者都有代码写权限。GitHub 的 Triage 角色适合管理 Issue、Discussion 和 PR，而不授予 push；创建或删除 Label、创建 Milestone、转移 Issue 等动作需要更高角色。不同动作的矩阵见GitHub repository roles。

GitLab 的 Guest 可创建 Issue，并能处理自己创建或被分配的部分对象；Planner 角色面向 Issue、Epic、Milestone、Iteration 和 Board 管理，不需要获得代码推送能力。Reporter、Developer、Maintainer 与 Owner 继续叠加其他权限。角色行为会随发行线调整，授予前应以目标实例的GitLab permissions做一次普通账号正反验证。

自动化优先使用安装到指定仓库的 GitHub App，或绑定目标 project/group 的 GitLab access token，不使用员工个人长期 PAT。GitHub fine-grained token 至少限制 resource owner、selected repositories 和 Issues 权限，具体 endpoint 所需权限可以从响应的 X-Accepted-GitHub-Permissions 判断，见fine-grained token 权限表。GitLab token 同时受 scope 与 bot 角色约束；api scope 很宽，若目标实例提供 granular scope，应优先限制到目标项目与动作。

凭证只通过 CI secret 或密钥系统注入，不能出现在 Issue 模板、Commit、命令历史、日志和截图中。Token 应有 owner、用途、目标资源、到期或轮换触发器与撤销入口。轮换时先让新凭证完成只读探测和一次实验写入，再切流，最后撤销旧凭证；直接撤销会让所有失败表现为同一个 401。

API 自动化先保证幂等，再追求实时

自动化最危险的不是漏处理一次，而是重试后重复创建 Issue、反复覆盖人工字段或错误关单。每条同步记录至少保存：

{
  "source": "monitoring",
  "source_event_id": "alert-LAB-42",
  "platform": "github",
  "host": "github.example",
  "container_id": "repository-id",
  "issue_id": "issue-id",
  "issue_url": "https://github.example/your-org/review-lab/issues/86",
  "last_seen_state": "open",
  "last_processed_delivery": "delivery-id"
}

source + source_event_id 是创建幂等键。收到重复 webhook 时先查映射，再更新已有对象。Issue 标题可编辑且可能重复，不能作为幂等键。机器人只写自己拥有的字段，例如 area:* 和同步评论；assignee、priority 或验收状态若由人负责，就不得整段覆盖。

GitHub REST 的 Issues endpoint 会把 PR 也作为 issue 返回，响应中带 pull_request 字段；统计普通 Issue 时必须排除它。创建或更新 Issue 所需 token 类型与权限应逐 endpoint 查看GitHub Issues REST API。GitLab Issues API 同时支持 Issue 元数据、跨引用和状态变更；私有 project 对无权限调用者可能返回 404，列表默认分页，自动化必须读取分页响应头而不是只处理第一页，见GitLab Issues API。

Webhook 比高频轮询更省请求，但不是恰好一次投递。接收端要持久化 delivery ID，验证签名或共享密钥，先落原始事件再异步处理；处理失败允许重放，业务更新保持幂等。轮询作为对账通道，定期寻找“已合并但未关单”“已关单但无验收”“Board 字段与 Issue 状态冲突”。

API 故障按证据分型：

401：Token 无效、过期、被撤销或认证头错误。403：身份已识别，但角色、scope、组织策略或速率限制阻止动作。404：路径或编号错误，也可能是私有资源对当前身份不可见。

409：资源状态冲突或并发更新不满足当前条件。422：字段、Label、Milestone、assignee 或状态变更不合法。429 或速率相关响应头：调用频率越过平台当前限制。

不要为一个 404 直接扩大到组织管理员。先用同一身份读取容器，再读取 Issue，再检查写 endpoint；把响应状态、request ID、delivery ID、速率响应头和脱敏 body 保存为故障证据。重试只用于超时、连接中断和平台明确允许重试的限流或服务错误；权限与校验错误必须修配置。

项目接入从一条可审计规则开始

团队第一次接入不需要上完整工作流引擎。选择一个高价值规则，例如“PR/MR 描述必须引用一个打开的 Issue，除非标记为紧急例外”，并把规则分成提示与阻断两阶段。

提示阶段只评论缺失项并采集误报：文档修正、依赖自动升级和纯运维变更是否真的需要 Issue？稳定后再把高风险目录、用户可见变更或数据库迁移设为阻断。例外必须有结构化原因、批准角色和后续补录 Issue，不能用管理员重跑绕过。

CI 检查器不应只用 /#[0-9]+/。它至少要解析完整引用，调用 API 确认目标可见、状态允许、PR/MR 与 Issue 归属合理，并把失败分成：没有引用、引用不存在、无权读取、Issue 已取消、跨仓库引用不完整。对于私有跨仓库引用，检查器身份必须同时拥有最小只读权限；否则会把真实 Issue 误判为不存在。

closing keyword 更适合“合并即可视为完成”的小变更。需要发布、数据修复、客户端升级或人工验收的工作，PR/MR 使用普通 reference，部署完成后由发布自动化附加证据，最终由 owner 关闭。自动化策略由问题失败模式决定，而不是为了减少一次点击。

敏感数据会沿通知链扩散

Issue 正文不是唯一副本。评论、编辑历史、邮件通知、移动端推送、附件、搜索索引、webhook payload、第三方机器人和导出包都可能复制内容。即使随后编辑正文，旧通知和外部日志也可能保留原值。

密码、Token、Cookie、私钥、客户原始数据和未脱敏生产日志不能进入 Issue。安全漏洞使用仓库安全策略指定的私密报告通道；客户事件使用受控工单，公开或普通工程 Issue 只保存影响摘要、脱敏证据和受控记录编号。GitLab confidential issue 能缩小可见人群，但 webhook、集成和导出仍需单独验证；GitHub 私有仓库也不能替代字段级数据治理。

机器人日志只记录资源 ID、动作、状态码和 request ID，不记录 Authorization、Cookie、Issue 全文和附件下载地址。调用第三方 AI 分类、翻译或摘要前，还要确认数据是否离开原平台、保留多久、是否用于训练以及删除请求能否传播到副本。

容量和成本首先消耗人的注意力

Issue 文本本身很少是最大成本。真正膨胀的是通知、重复工单、机器人评论、Project 字段、附件、搜索索引、API 调用、审计留存和无人处理的积压。

容量治理应观察趋势而不是套统一数字：新建与关闭流量是否长期失衡；无 owner、无验收标准和重复 Issue 是否持续增长；Board 查询是否因字段与自动化过多而变慢；webhook 重试与 API 限流是否增加；跨仓库查询是否总要扫描所有项目；迁移导出时间是否随 Issue、评论和附件增长而不可接受。

平台的 Projects、多个 Board、group planning、细粒度权限、审计、迁移工具、数据驻留和支持能力可能受产品方案、部署形态与区域影响。采购或扩容时现场核对 GitHub Pricing 与 GitLab Pricing，把真实成员、外部协作者、机器人身份、API 量、审计留存、迁移支持和退出成本代入，不写死金额或套餐名。

降低成本最有效的动作往往是收敛状态维度、合并重复机器人、减少无意义评论和明确 canonical tracker。给每个团队再建一块 Board 通常只会增加同步成本。

迁移不是把标题和正文搬过去

高保真迁移要保留的不只是 Issue 数量，还包括作者、评论顺序、状态、Label、Milestone、assignee、附件、交叉引用、PR/MR 关系、时间线和权限。任何一项映射失败，都可能改变审计含义。

迁移前在源系统建立不变量清单：

open_issue_count
closed_issue_count
comment_count
attachment_count
label_set
milestone_set
linked_change_count
cross_repository_reference_samples
restricted_issue_samples

目标系统导入后再次计算，并抽查高评论量、跨仓库、受限、带附件、已转移和自动关闭的样本。数量相同仍不代表关系正确；要从 Issue 反查 PR/MR，再从 PR/MR 反查 Issue，并确认旧 URL 的重定向或映射表。

GitHub 的迁移工具按来源和目标提供不同保真度，有的只迁代码与历史，有的还能迁 Issues、PR 和协作元数据。先从GitHub migration paths确认目标路径支持的工具与数据，再做试迁移。迁移日志即使显示完成，也要处理 warning；单条评论或评审线程可能没有迁入，不能只看任务成功状态。

GitLab project file export 能携带 Issues、评论、Labels、Milestones、Issue Boards 等大量项目数据，但官方明确指出它不是完整备份，且用户贡献映射、MR diff、集成和版本兼容存在条件；多数在线场景优先评估 direct transfer。具体对象随版本变化，应从GitLab project import/export核对源与目标版本。

迁移切换采用短暂停写而不是双向长期同步：先冻结模板与分类配置，完成最终增量或导出，导入目标，跑不变量和样本检查，切换 canonical URL，再把源系统改成只读。回退时恢复源系统写入、撤销目标机器人凭证、把切换期间新对象按映射补回源端。没有双向映射表就不能安全回退。

归档要保留证据，也要停止副作用

仓库或项目停止维护时，先关闭或转移仍活跃的 Issue，给替代项目留下稳定链接，再停机器人、webhook、定时同步和自动关单。只把仓库点成 Archived，却让外部机器人继续重试，会持续制造告警和失败日志。

GitHub archive 会让代码、Issues、PR、Labels、Milestones、Projects、评论与权限等对象变成只读，归档前应处理开放工作并确认替代入口，见GitHub repository archive。GitLab archive 同样让多数项目能力只读，还会停止部分自动任务；解除归档后，某些发布产物并不会自动恢复，见GitLab project archive。

Project 或 Board 中的卡片归档与仓库归档不同。前者只是降低活跃视图噪声，Issue 仍可变化；后者冻结容器。治理文档必须写清“归档的是视图项、Issue 还是整个仓库/项目”，否则恢复演练会操作错对象。

审计证据有三层，不能互相替代

Issue timeline 或 GitLab system note 适合解释“这个对象发生了什么”，例如谁加了 Label、谁关联了 MR、何时关闭。Webhook 日志适合解释“自动化收到了什么并做了什么”。组织、group 或实例级 audit event 则适合解释权限、设置、成员、Token 和管理动作。只保存其中一层，事故调查会缺关键上下文。

GitHub organization audit log 由组织 owner 访问，可搜索和导出；只需要接收持续事件时，webhook 可能比轮询 audit API 更合适。GitHub audit log说明了事件字段与访问方式。GitLab project/group/instance audit event 和 streaming 能力受方案与部署形态影响，stream 还可能重复投递，接收端要按事件 ID 去重，见GitLab Audit Events。

审计接收端保存 actor、动作、资源 ID、来源 IP 或代理信息、请求 ID、结果和原始事件哈希。Issue 正文与附件按数据分级另行保存，不要把整个 payload 无差别复制到低权限日志平台。审计缺少某个业务事件时，不能用机器人评论伪装平台审计；应通过 webhook 业务日志明确标注证据来源。

清理实验与错误自动化

实验结束后按依赖反向清理，先停自动化，再删对象：

禁用实验 workflow、webhook 和定时任务，确认不再有新 delivery。撤销实验 App 安装、project token 或临时 PAT，并验证旧凭证得到 401。删除或归档实验 Project 项、Board 和自定义字段。

关闭实验 Issue，删除实验 Label 与 Milestone；需要保留审计时不要永久删除 Issue。删除 lab-staging 和残留实验分支，移除 review-lab.txt 的实验变更。导出脱敏后的状态、请求 ID 和验证结果，清除包含凭证或正文的本地临时文件。

GitHub 实验对象可这样清理：

gh issue close "$ISSUE_NUMBER" \
  --repo "$GH_REPO" \
  --reason 'not planned' \
  --comment 'Closing disposable issue-link experiment.'

gh api --method DELETE "repos/$GH_REPO/milestones/$MILESTONE_NUMBER"
gh label delete 'type:bug' --repo "$GH_REPO" --yes
git push origin --delete lab-staging || true

如果自动化错误关闭了一批真实 Issue，先禁用写入者并保存 delivery 与请求证据，再按受影响清单恢复原状态。重新打开 Issue 只能修复生命周期状态；被覆盖的 Label、Milestone、assignee、Project 字段和评论还要分别恢复。代码已经错误合入时，代码回滚与 Issue 恢复是两条动作链，不能用 reopen 代替 git revert，也不能用代码回滚自动假设业务数据已经修复。

GitHub、GitLab 还是独立工单平台

如果团队的工作天然围绕 GitHub 仓库、PR 和组织级 Projects 展开，GitHub Issues 能以较低摩擦连接代码与计划。需要跨仓库时，应接受 Label、Milestone 的仓库局部性，用组织 Project 字段和完整引用建立统一视图。

如果团队使用 GitLab 的 project/group 层级、MR、group label、group milestone 和 group board，GitLab Issues 能把代码、计划与自建实例治理放在同一权限树中。相应代价是 Self-Managed 发行线、实例配置、后台任务和迁移兼容都进入团队责任，closing pattern 也可能由管理员改变。

当需求审批、客户服务、合规流转、复杂 SLA、资产关联或多部门权限远比代码关系重要时，独立工单平台更合适。代码平台只保存稳定外部工单 ID 与实现链接。不要双向复制所有字段；明确哪一端拥有标题、状态、优先级和验收，另一端只保留引用与少量派生状态。

选型试点应使用同一组失败场景：跨仓库引用、权限不足、模板失效、非默认分支合并、机器人重放、受限 Issue、迁移试跑和归档恢复。比较修复成本、审计完整性与退出保真度，比比较编辑器手感更接近长期现实。

让协作链长期可信

稳定运行的 Issue 系统有几条可验证的不变量：每个活跃 Issue 有 owner 或明确待分诊状态；每个实现 PR/MR 能追到 canonical Issue；每次自动关闭都能追到默认分支合并；每个高风险关闭都有发布或验收证据；每个机器人动作都有独立身份和 delivery 记录；每个跨仓库引用都携带命名空间。

模板、Label taxonomy、Project 字段、Board 查询、自动化规则和权限映射都应有 owner，并通过普通 PR/MR 变更。变更先在实验容器跑正反测试，再灰度到少量仓库。平台升级、权限模型变化、closing pattern 调整、迁移工具变化和产品方案调整都应触发重新验证。

长期治理不追求所有 Issue 都迅速关闭，而追求状态能够解释真实研发进度。一次故障发生时，任何接手者都应能从 Issue 找到问题证据、分类、Milestone、阻塞关系、Commit、PR/MR、默认分支合并、发布与验收；也能从一条代码变更反查它为什么存在、由谁接受、失败后怎样恢复。做到这一点，Board 才是团队现实的投影，而不是另一块需要人肉维护的彩色墙。