接手团队代码协作流程这半年最让我上火的不是业务代码本身而是每天没完没了地给人提 PR。Gitee 上仓库一多光是把分支提上来、选好 base、指派评审人这种机械操作就能耗掉一上午。后来我索性写了一套自动创建 PR 的小工具顺手把评审模式也接了进来今天就把这套方案从设计到落地的完整过程聊一遍希望能给同样被 PR 流程折磨的人一点参考。这篇内容不挑基础只要你在用 Gitee 管代码、被重复的合并请求创建流程烦过或者正好想给团队上代码评审制度但不知道怎么落地都可以直接照着做。核心就一件事让机器去干“创建 PR”这种重复劳动把人解放出来做真正有价值的代码评审。1. PR评审模式到底在解决什么问题1.1 先搞清楚“评审模式”的本质Gitee 的 PRPull Request本质上是一种“请求合并”的机制。你把自己的分支提交上去请求把代码合并到目标分支里。而评审模式就是在这个请求合并的过程中加入了“人审”的环节——代码不能直接合必须被指派的评审人看过、点过同意门禁才最终放开。我在团队里经常打一个比方没有评审模式的 PR就像去餐厅点完菜直接进后厨自己炒开了评审模式的 PR是必须经过传菜员核验菜品、大厨试味之后才能端上桌。前者效率高但出错没人把关后者多了一道工序却能把明显的问题在出锅前拦住。具体到 Gitee 上评审模式不只是一个按钮而是一套组合玩法创建 PR 时要能指定评审人仓库要配置合并保护规则来强制“评审通过才能合并”甚至可以在自动化脚本里把评审人字段一起传进去。这三件事咬合在一起才算是真正把评审模式跑通。1.2 手工创建PR的日常有多痛在没有自动化之前我们团队每周要发两次版本涉及十几个服务仓库。每次发版前我需要挨个仓库操作切到 release 分支确认代码 push 上去了然后打开 Gitee 网页新建 PR选 base 分支、写标题、贴描述模板再手动搜索评审人并指派。这个过程听着不复杂但架不住量大。十几个仓库每个仓库操作三五分钟一个上午就没了。更糟的是重复操作特别容易出错有一次我把一个仓库的 base 分支选错了从 release 合并到了 develop幸好评审人及时发现不然一堆开发中的代码就被带上了生产分支。还有一类痛点是“漏指派”。网页上手滑一下PR 建完了评审人没指派就在列表里躺着。没人看也没人合直到发布窗口过了才发现代码根本没过评审。这种事情出现两三次之后我就意识到必须用脚本把创建 PR 这个动作标准化、自动化把人为疏忽的可能性降到最低。1.3 自动创建PR如何与评审模式结合自动创建 PR 听起来就是把“点击按钮建 PR”换成“调 API 建 PR”但真正有价值的是把它和评审模式打通。我的做法是脚本扫描指定仓库的 release 分支如果发现分支领先于 master就自动创建一个 PR标题和描述按照统一模板生成同时把评审人字段一起传给 Gitee。评审人池是固定的几个技术负责人脚本按仓库和分支名做分配保证每个 PR 有两个人被指派。这样评审人每天打开 Gitee只会看到一个清晰的任务清单这是需要我看的 PR这是需要我拍板的合并请求。整套下来人要做的事情只剩一件打开 PR看代码点通过或驳回。创建 PR 的机械劳动全部交给脚本。1.4 这件事的影响范围很多人觉得“自动创建 PR”只是个效率工具实际落地之后影响面比想象中大不少。首先是流程规范性。脚本生成的 PR 标题、描述、标签都是标准化的不会出现今天叫“fix bug”明天叫“发版”这种随意标题后面翻历史记录、做版本追溯都方便。其次是质检前移。因为评审模式被强制开启所有代码在合并前必须经过至少一个评审人确认。我们自己统计过上线前被评审拦下来的问题修复成本大概是线上事故修复成本的三分之一都不到。哪怕只靠这个制度拦住一次重大事故工具和流程的投入就全值回来了。再就是审计和交接。PR 本身记录了谁在什么时候提了什么改动、谁评审的、谁合并的这套审计链在团队扩招、人员流动频繁的时候特别管用。新人接手老项目看 PR 历史比看文档更直观。2. 整体设计与工具选型2.1 一条完整的自动化链路在动手写代码之前我先把整条链路在脑子里过了一遍。典型的自动创建 PR 流程可以拆成这么几步确定仓库列表和需要检查的分支组合。获取每个仓库的分支信息比对 head 分支和 base 分支是否存在差异。如果存在差异再查询是否已经存在相同的 PR避免重复提交。调用 Gitee OpenAPI 创建 PR带上标题、描述、评审人和指派人。反馈创建结果输出 PR 地址方便后续追踪。这个链路里最容易被忽略的是第 3 步。很多刚开始写自动化脚本的人直接跳到第 4 步调接口创建 PR结果同一对分支连续创建了好几个重复的 PR把评审人烦得不行。我后来把查询已有 PR 的逻辑加在最前面重复创建这个问题就彻底消失了。2.2 备选方案横向对比实现自动创建 PR 的方式其实有好几种关键看团队的技术栈和维护成本。我先后试过几种各有优劣。方案优点缺点适用场景原生脚本curl / Python requests灵活、可控、无额外依赖需要自己维护 API 调用逻辑团队有 Python 或 Shell 基础追求轻量Gitee 官方 SDK封装了 API调用更省事更新维护节奏不一文档偶尔滞后想快速接入且熟悉语言生态Gitee Go 流水线插件和仓库集成度高无需自建调度依赖 Gitee 平台跨平台能力弱本身就在 Gitee Go 上做 CI/CD自动化平台 OpenAPI可视化编排非开发也能用引入额外系统学习成本高大团队统一管控运维平台我自己最终选的是 Python 脚本方案。原因很简单团队里 Python 熟练度最高而且脚本可以直接挂在 CI 或定时任务里不依赖任何额外的系统。Gitee 的 API 文档写得很清楚直接用 requests 调用并不复杂。2.3 令牌与权限的最小化设计用 OpenAPI 操作 Gitee 需要认证最常见的是使用私人令牌Personal Access Token。这块有个安全教训我必须强调令牌一定要按最小权限原则申请而且绝对不能硬编码在代码里。我见过有人图省事把令牌直接写进脚本文件然后整个仓库提交到 Gitee 上。令牌一旦泄露别人就可以用你的身份建 PR、改仓库设置、甚至删分支。正确做法是把令牌放到环境变量或 CI 的 Secrets 里脚本运行的时候从环境里读取。在 Gitee 上创建私人令牌的时候权限范围可以精细勾选。对自动建 PR 这个需求来说只需要 projects 相关的读取权限和 pull_requests 的写权限就够了其他权限一律不勾。这样即使令牌真的不幸泄露攻击者能做的事也被限制在一个很小的范围内。3. 手把手写一个自动创建PR的脚本3.1 准备环境与令牌申请开始写脚本之前先把环境准备好。你需要一个能跑 Python 的机器Python 3.6 以上版本就行再用 pip 装一下 requests 库pip install requests然后去 Gitee 申请私人令牌。路径是Gitee 右上角头像 → 设置 → 安全设置 → 私人令牌 → 生成新令牌。生成时有两个点要注意权限范围勾选 projects读取和 pull_requests写入即可。令牌只显示一次生成后立刻保存到环境变量里。Linux 或 macOS 下可以用 export 临时导出CI 平台就放到对应的 Secrets/变量配置里export GITEE_TOKEN你的令牌脚本里读取环境变量的方式尽量统一后面维护起来省心。3.2 核心实现自动建PR并指派评审人下面这段是我在实际项目里跑过的简化版本。核心逻辑就两块先查重再创建。import os import requests GITEE_API https://gitee.com/api/v5 TOKEN os.environ.get(GITEE_TOKEN, ) OWNER your_org # 组织或个人命名空间 REPO demo-service # 仓库名 headers {Content-Type: application/json;charsetUTF-8} def list_pulls(stateopen): 列出仓库的所有PR用于查重 url f{GITEE_API}/repos/{OWNER}/{REPO}/pulls params { access_token: TOKEN, state: state, per_page: 100, page: 1, } pulls [] while True: resp requests.get(url, paramsparams, headersheaders) resp.raise_for_status() batch resp.json() if not batch: break pulls.extend(batch) params[page] 1 return pulls def create_pr(title, head, base, body, reviewersNone): 创建PR并指定评审人 url f{GITEE_API}/repos/{OWNER}/{REPO}/pulls data { access_token: TOKEN, title: title, head: head, base: base, body: body, reviewers: ,.join(reviewers or []), assignees: ,.join(reviewers or []), } resp requests.post(url, jsondata, headersheaders) resp.raise_for_status() return resp.json() def find_existing_pull(pulls, head, base): 在已存在的PR里找相同分支组合 for pr in pulls: if pr[head][ref] head and pr[base][ref] base: return pr return None if __name__ __main__: HEAD release/1.2.0 BASE master existing_pulls list_pulls(open) duplicate find_existing_pull(existing_pulls, HEAD, BASE) if duplicate: print(f已存在相同PR跳过创建: {duplicate[html_url]}) else: pr create_pr( titlerelease/1.2.0 - master 发版合并, headHEAD, baseBASE, body自动化生成的发版PR请重点检查配置变更和数据库脚本。, reviewers[alice, bob], ) print(fPR创建成功: {pr[html_url]})两个细节值得展开说一下。第一list_pulls 里我用了分页循环per_page 设成 100然后一页一页翻。一开始我只请求第一页结果 PR 一多查重逻辑就漏了同一个分支组合被建了好几个 PR。加成分页之后才彻底修好。第二reviewers 和 assignees 都传了同一个列表。区别在于 reviewers 是真正要做代码评审的人assignees 是负责跟进这个 PR 的人。对大多数团队来说这两个角色往往是同一个人但也有分开的场景比如 assignees 是实习生reviewers 是导师。3.3 评审模式的最终落地合并保护到这里PR 能自动建了评审人也指派了但离“评审模式”真正生效还差最后一步——仓库的合并保护规则。我自己一开始就吃过这个亏。脚本建完 PR、指派了评审人我以为万事大吉了结果同事直接在 Gitee 网页上点了“合并”按钮PR 就合了评审人根本没来得及看。原因很简单光指派评审人只是一个“请求”不等于“强制”。真正的强制要在仓库设置里开。路径是仓库 → 管理 → 分支设置 → 保护分支。对 master或其他核心分支开启保护然后勾选“需要评审通过后才能合并”之类的选项。不同版本 Gitee 的菜单位置可能有差异但核心逻辑是一致的把“评审通过”设置为合并的前置条件。这一步如果不想手工去点也可以查一下 Gitee OpenAPI 有没有对应的接口或者至少把配置方法写进团队文档里。我的建议是不管用哪种方式这个规则必须有人负责维护否则评审模式就是纸糊的看起来存在一推就倒。3.4 挂到定时任务或CI里脚本写完之后接下来就是让它按时跑起来。最简单的办法是 crontab。比如每个工作日上午十点检查一次所有仓库的 release 分支0 10 * * 1-5 cd /opt/gitee-pr-bot python create_release_pr.py logs/pr-bot.log 21如果你团队已经上了 Gitee Go 或者别的 CI 系统也可以把脚本作为流水线的一个步骤。相比 crontabCI 的好处是有现成的调度界面和日志中心失败了能直接看到告警通知。我在实际落地时选择的是“定时执行 人工兜底”的组合脚本定时跑跑完把结果发到团队群里如果当天有临时需求要立刻提 PR再手动补一个。机器负责例行公事人负责异常情况两边不耽误。注意脚本刚写完的时候不要直接全量铺开跑所有仓库。先挑一个不重要的仓库试运行几天确认查重逻辑、评审人分配、通知触达都正常了再扩大范围。4. 常见问题与排查记录4.1 鉴权失败401和403的区分脚本上线之后最先遇到的就是鉴权问题具体表现是调用 API 时报 401 或 403。两者的含义不一样。401 是 Unauthorized说明令牌本身有问题可能过期了、被吊销了或者压根没传进去。排查思路就三步先确认环境变量 GITEE_TOKEN 有没有正常导出再检查令牌是不是被误删最后确认令牌内容有没有复制完整比如多复制了一个空格就会导致鉴权失败。403 是 Forbidden多半是权限不足。这时候重点检查私人令牌的权限范围是不是只勾了 projects 读取而没勾 pull_requests 写入。或者操作的对象超出了令牌持有者的权限比如普通成员想给 protected 分支建 PR 被拒绝。给一张速查表方便对照现象含义排查方向HTTP 401令牌无效或缺失环境变量、令牌是否过期、字符串是否完整HTTP 403权限不足令牌权限范围、用户仓库权限、分支保护规则HTTP 404资源不存在仓库名/组织名拼写、API路径是否正确HTTP 422参数校验失败必填字段缺失、分支名错误、评审人不在仓库成员列表4.2 重复PR同一个分支被反复提审重复 PR 是我掉过的第二个坑。最初脚本没有查重逻辑crontab 每跑一次就建一个新 PR。两天下来同一个 release 分支在 Gitee 上挂着四五个一模一样的 PR评审人都不知道到底该看哪个。后来我把查询已有 PR 的逻辑前置并且判断条件精确到 head 分支和 base 分支的组合。只要存在 open 状态的相同组合 PR就直接跳过创建。另外还要注意一点已经关闭的 PR 是否要参与查重取决于你的业务。如果关闭的 PR 是“被驳回后重新提”那最好允许新建如果是“误操作关闭”那还是跳过更合理。4.3 评审人收了通知却看不到入口有一种情况很隐蔽脚本明明成功指派了评审人评审人也收到了通知但点进 PR 页面发现状态不太对看不到评审入口。我遇到过的原因有两类。第一类是评审人不在仓库成员列表里。Gitee 的评审人指派是有约束的不是随便填一个用户名就行这个人必须对该仓库有访问权限。解决方案是在脚本里加一个校验步骤调用仓库成员接口核对名单不在名单里的人自动替换成候选评审人。第二类是分支保护规则没配好。如果仓库没有开启“评审通过后才能合并”那 PR 页面可能不会展示完整的评审状态模块。这个就跟 3.3 节说的一样光指派人不强制等于没评审。4.4 开完PR就红一片的风控自动创建 PR 还有一重风险如果目标分支上有 CI 校验脚本建完 PR 之后流水线可能立刻跑一大堆检查然后红成一片。本身这不是脚本的锅但会影响评审体验而且如果 CI 资源紧张十几个 PR 同时触发的并发压力也不小。我的经验是分两步走。第一步在创建 PR 前先在脚本里自动触发一次分支的静态检查比如编译、lint、单元测试。检查不通过就直接告警根本不给它进到“等待评审”的状态。第二步控制批量创建的速度每创建完一个 PR 停顿几秒避免集中请求把 API 配额打满。5. 真实体验与几条建议这套自动创建 PR 评审模式的方案团队跑了快一个季度最直观的感受是流程变轻了。以前发版前半天都在重复劳动现在脚本十分钟跑完人只需要打开群消息里的 PR 链接点进去看代码、提意见、点通过。评审质量肉眼可见地提升了因为大家有精力去认真看代码了而不是赶时间机械地点“通过”。我自己踩过最大的坑不是技术问题而是“没有把评审模式真正强制住”。脚本写了、评审人指了但分支保护没开等于所有功夫白费。如果你要落地这套方案第一件事不是写脚本而是先把目标分支的保护规则配好让人不能跳过评审直接合并。另外建议工具刚上线时先把日志和通知做完善。每条 PR 是新建了、跳过了还是报错了都打到日志里并推送到群方便随时回溯。脚本跑得再顺也要有“人工兜底”的意识毕竟自动化的目的是解放人而不是制造新的黑天鹅。