阅读导览
合并请求(Pull Request,简称 PR)把一个分支的修改提交给目标分支审查。它包含讨论、提交、文件差异、评审结果和检查状态。仓库写入权限、合并权限与分支保护并不等价;能推送功能分支的人不一定能合并主分支。
先确认仓库支持合并请求
合并请求的标准列表地址是 /拥有者/仓库/pulls,议题是 /issues。不要用地址名称判断两种功能的用途。仓库必须启用合并请求、具有代码内容并允许修改,账号也需要对应读取权限。
当前镜像仓库、归档仓库和空仓库不满足正常发起合并的条件,因此单独勾选功能开关也可能不出现可用入口。来自其他平台的一次迁移不会持续同步后续 PR。镜像与迁移的区别见仓库管理。
准备分支或派生仓库
- 有写入权限时,在仓库中推送一个独立功能分支;没有写入权限时,按页面允许的方式派生仓库,在自己的派生中开发。
- 保持目标分支清楚,例如上游
main;不要把功能分支误当目标分支。 - 检查暂存内容与提交记录,移除临时文件、密钥和无关格式化。
- 本地完成适合修改的测试后再发起 PR,相关命令见Git 操作。
派生操作不改变上游仓库权限,也不会让私有项目变成可以公开传播的内容。
创建并写清修改范围
- 打开仓库“合并请求”,选择新建或比较分支入口。
- 核对目标拥有者、仓库和分支,以及来源拥有者、仓库和分支。
- 写一个描述结果的标题,在正文说明问题、修改行为、验证方式和剩余限制。
- 关联相关议题,按团队流程选择评审者或标签,再提交。
工作尚未就绪时可以使用界面支持的草稿状态或未完成标记。就绪后需要解除草稿状态;被标记为尚未完成的工作时,系统会阻止合并,这不是代码冲突。
阅读差异并完成评审
“文件变更”按文件展示新增和删除内容,可对具体行发评论。评审者应结合上下文检查行为、权限和测试,不要只看绿色检查图标。使用请求修改或通过评审前,确认意见已经表达清楚。
作者回复意见后,向同一个来源分支推送新提交,PR 会随之更新。大幅重写提交历史会影响讨论上下文,协作前应先沟通。对每条意见给出处理结果,遗漏的事项明确记录,方便评审者复查。
处理检查失败和冲突
- 状态检查失败时,进入对应工作流或检查详情,先找到第一个实际错误。
- 分支落后或冲突时,在本地同步目标分支,按团队约定合并或变基。
- 逐个解决冲突,重新运行测试,再推送来源分支。
- 回到 PR 确认差异、评审和检查状态是否满足保护规则。
界面的“更新分支”只在满足条件时出现,不能替代复杂冲突处理。自动构建依赖 Runner;长时间等待也可能是没有匹配的在线构建机,详见自动打包。
选择合并方式并检查结果
仓库可配置合并提交、压缩提交、变基或快进等方式;界面只显示当前允许且满足条件的选项。维护者在合并前核对目标分支、提交说明、评审要求和关联议题,再执行确认。
合并后检查目标分支是否出现预期修改,再按团队策略删除已经完成的来源分支。删除分支不会删除 PR 讨论,合并也不会自动发布安装包。需要交付版本时继续创建发布。自动合并若可用,仍需等所需条件满足后才执行。
使用 AGit 发起请求
当前代码支持 AGit 流程,可通过推送评审引用发起或更新 PR,适合熟悉 Git 的用户。例如在允许的仓库和协议环境中使用:
git push origin HEAD:refs/for/main/topic-example
这里 main 是已存在的目标分支,topic-example 是主题名。它会进入评审流程,不能直接绕过分支保护写入 main。站点、Git 协议或仓库权限不满足条件时会被拒绝;首次使用先在测试仓库验证,并以系统返回的 PR 地址为准。