84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
# 代码托管平台适配
|
||
|
||
## 区分 Git 与 Forge 能力
|
||
|
||
fetch、查询 remote refs、推送分支和推送单个 tag 属于 Git transport 能力，可直接通过
|
||
已配置的 Git remote 完成。创建或查看 PR/MR、合并以及创建 Forge Release 才需要平台
|
||
CLI。只发布 tag 时，不要因为缺少 Forge CLI 而停止；仍要验证 remote、认证目标和推送
|
||
授权，并在 push 后读回远端 ref。
|
||
|
||
## 选择 Forge 适配器
|
||
|
||
从 push remote URL 识别平台，并使用对应官方 CLI：
|
||
|
||
| 平台 | CLI | PR/MR 命令域 | Release 命令域 |
|
||
|---|---|---|---|
|
||
| GitHub | `gh` | `gh pr` | `gh release` |
|
||
| GitLab | `glab` | `glab mr` | `glab release` |
|
||
| Gitea / Forgejo | `tea` | `tea pulls` | `tea releases` |
|
||
|
||
先运行 CLI 的版本、认证状态和只读查看命令。记录匹配 remote host 的活动账号；存在多
|
||
个账号或 profile 时，必须唯一确定本次使用的身份。CLI 版本之间的 flags 可能不同，
|
||
每次执行写操作前读取对应子命令的 `--help`，不要凭记忆拼接参数。
|
||
|
||
直接从目标 worktree 的当前 shell 运行 `git` 与平台 CLI，让它们使用各自正常的登录机制。
|
||
Gitea/Forgejo 使用 `tea whoami` 和 `tea` 对应子命令；不要由 Agent 读取 tea 配置文件、
|
||
调用 credential helper 导出 token，或把 token 转存到命令参数、环境文件和发布说明。
|
||
|
||
当请求确实涉及 PR/MR、合并或 Forge Release，且 remote host 无法识别、CLI 缺失、认证
|
||
失败或 CLI 指向另一个实例时，停止对应平台阶段并报告：
|
||
|
||
- host、owner/repository、remote 名称。
|
||
- base、head 和当前 commit。
|
||
- 已完成的本地验证。
|
||
- 尚需人工执行的创建 PR/MR、合并或 release 步骤。
|
||
|
||
不要自动安装 CLI，也不要把 token 放进命令行后改用 `curl`。用户明确提供受支持的其他
|
||
集成时，可以使用该集成，但仍遵守同一套授权和验证闸门。
|
||
|
||
## 创建 PR/MR
|
||
|
||
使用显式的 repository、base、head、title 和 body，避免交互式默认值改变目标。把动态
|
||
值作为独立 argv 或结构化输入传递，不拼接 shell 命令。创建前：
|
||
|
||
1. 确认当前分支已经推送到计划中的 remote。
|
||
2. 查询同一 head/base 是否已有 open PR/MR，有则复用并更新状态，不重复创建。
|
||
3. 确认 head commit 与本地已验证 commit 相同。
|
||
4. 确认 CLI 不会隐式创建 fork 或推送到另一个 remote。
|
||
5. 再次读取活动账号，向用户展示 host、repository、账号和授权的最远阶段。
|
||
|
||
PR/MR body 包含目标版本、变更摘要、验证命令与结果、发布后续。创建后读取平台返回的
|
||
URL、编号、head/base 和状态，不以命令退出码代替远端读回。
|
||
|
||
## 检查和合并
|
||
|
||
用结构化输出读取 draft、head commit、base、review、required checks、冲突或
|
||
mergeability、允许的合并方式。平台字段缺失时，使用平台提供的只读详情命令补足；不能
|
||
证明闸门通过时保持未合并。
|
||
|
||
GitHub 使用 `gh pr view`、`gh pr checks` 和 `gh pr merge`；GitLab 使用
|
||
`glab mr view`、pipeline 状态和 `glab mr merge`；Gitea 或 Forgejo 使用
|
||
`tea pulls` 的查看、检查和合并能力。实际参数以当前 CLI 的 `--help` 为准。
|
||
|
||
若用户要求检查通过后自动合并，优先使用仓库已经启用的 auto-merge 或 merge queue。
|
||
不要用管理员选项绕过 review、CI、conversation resolution 或 protected branch。
|
||
|
||
合并后重新读取 PR/MR，取得平台确认的 merged commit。随后 fetch 远端 base，并验证该
|
||
commit 已进入远端 base。只看到本地 merge commit 或分支关闭不足以证明平台已合并。
|
||
|
||
## 创建 Forge Release
|
||
|
||
把 Git tag 和 Forge Release 当成两个独立状态。先创建、推送并验证包含完整更新说明的
|
||
annotated tag，再创建 release。Forge Release 正文复用已经冻结并验证的 tag 更新说明，
|
||
不要重新生成另一份内容。
|
||
|
||
- GitHub 创建 release 时使用能够拒绝缺失 tag 的选项，例如当前 CLI 支持的
|
||
`--verify-tag`。
|
||
- GitLab、Gitea 或 Forgejo 创建 release 前，先用只读命令证明 tag 已存在并指向计划的
|
||
commit、tag object 包含计划的更新说明；不要使用会顺便创建 tag 的默认行为。
|
||
- 预发布版本按项目规则标记 prerelease，不要自动把它标为 latest 或 stable。
|
||
- 发布后重新读取 release URL、tag、正文和可见性，确认正文与 tag 更新说明一致。
|
||
|
||
Forge Release 创建失败但 tag 已成功推送时，保留 tag 并从 release 阶段恢复，不要重新
|
||
合并或创建另一个 tag。
|