如果你的日常工作流还停留在“把Gitee当成免费网盘clone下来push上去就完事”那你可能只用了这个代码托管平台一半以上的能力。我在过去几年带过好几个小团队从最开始互相clone压缩包传文件到后来把需求管理、代码评审、自动构建全部跑在Gitee上最大的感受是Gitee不只是存代码的地方它围绕代码托管延伸出的协作能力完全能撑起一个中小型团队的项目中枢。这篇分享我就从注册账号、配置SSH开始一路讲到分支策略、Pull Request评审、保护分支和自动化触发希望能帮你把Gitee真正用成“团队协作神器”。这套内容适合两类人一类是刚接触代码托管的新手照着步骤走就能把仓库跑起来另一类是用Gitee但只用基础功能的老用户可以顺手把当前工作流里缺失的环节补上。1. 为什么我把团队主力仓库迁到了Gitee1.1 国内网络的现实问题时快时慢的连接体验早期我们团队一度把仓库放在海外托管平台日常用起来最头疼的就是速度。你以为这只是“慢一点”的问题实际上全量clone一个几百MB、包含完整历史的仓库时经常卡在某个对象的解压阶段半小时后整个目录消失只能重来。团队成员分布在不同城市有人拉取五分钟有人拉取半小时每次新人入职光clone代码和环境准备就能耗掉一上午。把主力仓库迁到Gitee之后这种现象基本消失了。服务器在国内网络路径短大仓库的clone和push都能稳定跑完。对于需要频繁拉取最新代码、一天可能要操作几十次的场景这个稳定性比任何花哨功能都重要。后来我们总结出一个判断标准如果一个操作会让团队等超过十秒那这个操作每天重复一百次消耗的就是生产力。1.2 Gitee与海外托管平台的差异对比很多人以为国内外的代码托管平台只是“换了个皮肤”实际差异比想象中大。我按日常使用频率做了一个粗略对比维度Gitee海外平台(GitHub等)访问速度国内节点拉取推送稳定海外节点访问时快时慢私有仓库个人和团队私有仓库免费额度友好免费私有仓库面向小团队限制不少中文界面原生中文文档齐全中文是翻译版部分术语不一致社区生态国内开发者活跃中文讨论多国际开源项目更集中CI/CD提供Gitee Go等自动化流水线有成熟的Actions体系静态站点Gitee Pages可用有Pages但国内访问不稳定合规与数据数据存放在境内容易满足内部要求数据存放在境外敏感项目要掂量这里不是要分个高下而是说明选择的逻辑如果你服务的主要用户在国内团队开发主力也在国内那平台本身的访问稳定性就是第一优先级。开源项目做国际推广自然可以把海外平台作为主阵地内部业务系统、外包交付、课程Demo放在Gitee明显更顺手。1.3 什么样的仓库适合放Gitee什么样的不适合结合我们的迁移经验适合放Gitee的主要有三类第一类是内部业务系统代码不对外公开、又不想被海外网络拖慢私有仓库免费这个特性非常实用第二类是外包交付项目需要把代码托管、Issue记录、版本发布放在一起方便跟甲方对账第三类是课程教学和个人练手Demo中文界面和国内访问速度大大降低了新手的学习成本。不适合或者需要谨慎的是那些高度依赖海外开源生态的大型公共开源项目。这种项目的贡献者分布在全世界PR和Issue的协作节奏必须考虑国际时区强行把主仓库放国内反而增加参与门槛。常见的做法是主仓库留在海外在Gitee上开一个镜像仓库方便国内用户拉取代码、提交Issue。镜像同步属于平台提供的常规功能配置一次之后两边代码会自动保持一致。2. 账号准备与SSH配置把协作的地基先打好2.1 注册、实名与团队用户名约定Gitee注册没什么门槛手机号加邮箱就能完成。这里说两个容易被忽略的点。第一实名认证要早做。Gitee的Pages功能、部分企业级能力会要求实名等你想用的时候再认证会卡住发布时间。个人实名只需要在账号设置里按流程走一遍几分钟的事不要拖到项目上线前一天才想起来。第二用户名要提前统一。团队里我的做法是要求所有人的Gitee用户名和常用社交账号保持一致不许用“dev_001”这种编号。因为代码评审时协作者第一眼看到的是用户名如果每个人都是随机字符根本分不清这条评论是谁留的。用户名就是你在协作场景里的身份ID越可读越好。2.2 生成SSH Key并添加公钥五分钟做完的事推荐用SSH方式访问Gitee仓库免去每次输入密码也更安全。生成密钥的命令很简单ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车即可默认会在~/.ssh/下生成id_ed25519私钥和id_ed25519.pub公钥。然后查看公钥内容cat ~/.ssh/id_ed25519.pub复制整段公钥打开Gitee页面右上角头像 → 设置 → 安全设置 → SSH公钥 → 添加公钥粘贴保存。验证是否配置成功ssh -T gitgitee.com首次连接会提示确认主机指纹输入yes回车。如果配置成功会返回一条表示验证通过的信息。这里有个新手常见问题公钥添加后仍然报Permission denied (publickey)。八成是粘贴公钥时少了前缀或后缀或者用的是另一台机器的公钥。如果公司电脑和家里电脑都要推送两台机器要各自生成并添加公钥Gitee允许同一账号绑定多把公钥全部加进去就行。2.3 SSH和HTTPS怎么选以及两三件必须注意的小事HTTPS方式clone时不需要提前配SSH Key适合一次性下载代码。但每次push大概率要输入用户名密码除非在Git配置里缓存凭据。日常开发建议优先SSH配置一次之后所有操作都不需要反复认证。还有几个小细节值得注意。第一全局Git身份要设置好否则提交记录会显示成无名用户git config --global user.name 你的用户名 git config --global user.email 你的邮箱example.com这里的名字和邮箱最好与Gitee账号保持一致。这样提交历史能正确关联到账号代码评审时点击提交人就能跳到对应主页。第二Windows和macOS混用的团队换行符会自动转换建议在Windows侧执行git config --global core.autocrlf truemacOS/Linux侧保持默认避免每次pull都出现“整个文件被修改”的假diff。3. 建仓的几种常规路线与初始化规范3.1 网页端新建仓库模板和许可证怎么勾网页端新建仓库是最直观的方式。在Gitee首页点“新建仓库”填写仓库名称和路径选择公开还是私有然后会看到三个选项初始化仓库、添加README、添加.gitignore。新手容易忽略的是.gitignore。不选这个模板的话本地一堆编译产物、IDE配置文件会被一并提交上去仓库很快变得脏乱。Gitee提供了Java、Python、Node、Go等常用语言的模板新建时按项目语言选一个即可。即便忘了选之后把模板文件补进仓库也能生效。开源许可证方面如果仓库要对外开源推荐MIT或Apache-2.0。MIT足够简短适合不纠结细节的团队Apache-2.0多了专利授权条款适合企业背景的开源项目。内部私有项目不需要许可证选“无”就行。3.2 把本地已有项目推上Gitee从init到push很多时候我们不是从空仓库起步而是本地已经写了一堆代码。这时采用“先有本地仓库再关联远程”的路线git init git add . git commit -m chore: initial commit git remote add origin gitgitee.com:用户名/仓库名.git git push -u origin master需要强调的是正式提交前务必检查是否有敏感信息混入。常见事故是把数据库密码、API密钥、本地配置文件传上仓库一旦push出去即便删掉也会留在历史记录里。所以第一次提交最好给仓库配置好.gitignore运行仓库路径与URL扫描工具跑一遍再执行add和commit。3.3 从其他平台迁移仓库完整保留分支与Tag历史从海外平台迁回Gitee或是反向迁移最怕丢历史。推荐用裸仓库加镜像推送的方式git clone --bare gitgitee.com:用户名/旧仓库.git cd 旧仓库.git git push --mirror gitgitee.com:用户名/新仓库.git--bare克隆的是不含工作区的完整仓库--mirror会把所有分支、标签、引用一次性推给新地址。实际验证下来这个方式能完整保留提交历史。但迁移不等于复制数据仓库的成员权限、分支保护、WebHook、CI配置都要重建一遍建议把迁移清单列好按项检查。4. 日常提交与撤销动作背后的分支策略4.1 提交信息规范让每一条历史都值得回看团队代码评审时最痛苦的事是看到一个commit message只写着“update”或“修改”。追溯问题时完全不知道这个提交改了什么、为什么改。我们后来统一用了社区成熟的提交信息约定简单说就是给提交分类打标签feat新功能fix修复Bugdocs只改文档refactor重构不改功能test增加测试chore构建、依赖等杂项一个典型提交长这样feat(order): 增加按日期的订单数量统计 - 新增日期分组查询接口 - 前端列表页增加筛选条件 - 补充单元测试 关联 #23Gitee会自动识别提交信息里的#23并关联对应Issue评审人点进去就能看到来龙去脉。我们对团队的要求是一个提交只做一件事逻辑独立的改动要拆开提交这样回滚时只需要精准撤回某个提交不会连累其他功能。4.2 常用分支模型与命名习惯单分支直接推master的做法在团队协作里走不远。我强烈建议所有改动都走功能分支主分支永远保持可发布状态。分支命名用前缀区分意图feature/订单导出新功能fix/登录超时缺陷修复release/v2.0.0发布准备docs/读我说明文档调整实际开发中从主分支切出功能分支开发完成后合回主分支删除远程功能分支。主分支名字是master还是main不重要重要的是整个团队统一。Gitee新建仓库时可以设置默认分支名建立仓库那一刻就要定好后面再切换会麻烦很多。4.3 撤销操作的三个层次以及已推送提交的正确回退方式git 撤销操作经常让新手失眠因为不同命令的后果差异很大。按影响范围从小到大排列命令作用适用场景git reset --soft只撤销commit保留暂存区和改动提交后发现message写错了git reset --mixed(默认)撤销commit和暂存保留工作区改动提交后发现漏了文件想重新整理git reset --hard全部丢弃连工作区改动一起清掉彻底放弃该提交慎用如果提交已经push到了远程而且团队其他人可能已经拉取过这时候千万不要用reset去回退再强制推送那样会覆盖别人的本地历史造成混乱。正确做法是生成一个反向提交git revert HEADgit revert会新增一个提交逻辑上等于“撤销上一次改动”但历史是向前走的所有人都能安全拉取。我们团队的原则很简单没推送过的提交随便reset推送过的提交一律revert。万一错误执行了git reset --hard还有最后一根救命稻草git reflog找到丢失提交之前的哈希值再用git reset --hard 哈希值恢复。我在一次误操作里靠这个方法救回过大半天的产出所以只要本地仓库打开过reflog误删提交多半还有救。4.4 推送被拒的常见场景与应急处理推送失败不一定是操作错误更多是协作状态不同步。最常见的是non-fast-forward意思是远程分支有本地没有的新提交。解决方式git pull --rebase origin 当前分支名rebase会把本地提交“搬”到远程提交之后提交历史保持线性比直接merge产生的分叉好看好读。遇到冲突就在rebase过程中逐个解决解决完再继续git add 冲突文件 git rebase --continue git push另一种被拒是因为触发了保护分支规则提示没有权限直接推送到该分支。这时候不要想着绕过规则应该把改动提交到专门的功能分支然后在Gitee上发起Pull Request走评审流程合入。还有一种情况是推送超大文件被平台拒绝一般单文件超过平台配额就会报错解决思路是引入Git LFS大文件存储把体积大的二进制文件托管到LFS仓库本身只保存指针。5. Pull Request评审从一个人提交到一群人把关5.1 一次标准PR从创建到合并的完整路径Gitee的Pull Request简称PR是代码评审的核心入口。一个标准流程是从主分支切出功能分支开发并提交代码推送功能分支到Gitee远程仓库在仓库页面上方进入“Pull Requests”点击新建选择源分支功能分支和目标分支主分支填写标题和描述关联相关Issue指定评审人点击创建评审人在PR页面查看diff、留下行内评论开发者根据意见追加提交提交会自动更新到PR评审通过后点击合并很多团队用了很久Gitee却完全没点开过Pull Requests这个入口等于把最值钱的协作机制闲置了。没有PR的代码合入就像是没人检查的工单直接上线问题由用户来发现成本高得多。5.2 让人愿意认真review的PR写法代码评审质量不取决于评审人多严格很大程度上取决于PR描述写得好不好。我们团队使用了固定模板新人照着填就行## 背景 为什么需要这个改动关联的Issue ## 改动内容 - 改动点1 - 改动点2 ## 影响范围 涉及哪些模块是否需要同步更新文档 ## 测试情况 - 已验证场景 - 未覆盖场景 ## 其他备注 部署注意事项、数据库变更等除此之外还有几条不成文规则一个PR只解决一个问题尽量控制在几百行以内超过一千行的PR评审人看到就头大评审判定很容易走马观花推送之前自己先把diff从头到尾过一遍减少明显的低级错误。把PR看作一次书面沟通写清楚的人往往能更快拿到合并许可。5.3 三种合并方式的选择merge、squash还是rebaseGitee提供多种PR合并方式选错了会让历史变得难以梳理。三种方式的差异合并方式历史效果适用场景Merge提交保留PR所有提交多一个merge提交想让主分支时间线保留真实全过程Squash合并把PR整体压缩成单个提交功能分支上的零碎提交没保留价值Rebase合并PR提交逐个重放到目标分支历史线性希望历史干净又想保留每次提交我们团队日常以squash为主功能分支上那些“fix typo”“补充测试”的中间状态没必要留在主干历史里压缩成一个完整提交最清爽。发布分支则用Merge提交让发布节点有明确的合并记录。不管选哪种只要全团队约定一致历史都不会太难读。5.4 冲突处理别慌先把目标分支拉进来PR合并时经常出现“有冲突无法合并”的提示这通常不是大问题只是目标分支在你开发期间有了新变化。常见做法是把目标分支合并到自己的功能分支在本地解决冲突再推送回来git checkout 功能分支 git fetch origin git merge origin/master # 冲突文件手动解决 git add . git commit git pushPR会自动更新冲突状态消失后就可以合入了。要减少冲突核心习惯是功能分支不要活太久两天以上的分支最好每天同步一次目标分支不要攒到最后一次性解决堆积的冲突。6. Issue、Wiki、Pages与自动化把仓库变成项目中枢6.1 Issue与里程碑需求、Bug和版本迭代的管理入口很多团队把Issue当成可有可无的便签实际它是需求管理的绝佳容器。我们团队在Gitee上维护了一套简单的Issue规范Bug类模板固定包含“环境信息”“复现步骤”“期望行为”“实际行为”需求类模板包含“用户故事”“验收标准”。创建Issue时打上标签——bug、feature、improvement——再挂到对应的里程碑一个迭代的目标立刻清晰起来。提交代码时在commit message里写#Issue编号代码评审和Issue就能双向关联。比如修复Issue #12的提交会在Issue页面显示出来评审人、测试人员点过去就能追踪修复过程。这个串联机制看起来简单却是让仓库从“代码堆”变成“项目管理工具”的关键一步。6.2 Wiki和Pages把文档和官网放在代码旁边Gitee仓库自带Wiki适合放README承载不了的长篇文档接口约定、部署手册、操作指引、架构说明。和README的分工是README是仓库门面让陌生人一分钟内知道项目是干什么的、怎么跑起来Wiki是文档库承载日常维护和协作过程中的完整资料。Gitee Pages可以基于仓库生成静态网站玩法和海外平台的GitHub Pages类似。个人博客、项目官网、产品介绍页都能直接托管。需要注意Pages一般要求完成实名认证每次更新代码之后需要重新构建发布不是push完秒生效所以发版流程中要给构建和审核预留时间。我们用Pages做过一个项目的在线文档站把README、Wiki、API文档集中到一个站点外部合作方访问起来比翻仓库方便得多。6.3 WebHooks与CI/CD提交之后自动触发最优美WebHook是Gitee向外部系统推送事件通知的通道。配置路径一般在仓库的管理设置里选择触发事件——比如push、PR创建、Tag推送——填写一个公网可访问的回调地址。代码一推送Gitee就把JSON数据发到这个地址。我们最常见的用途是对接群机器人push后群内自动出现提交摘要PR合并后自动提醒测试人员部署省掉大量“代码推了你去拉一下”的口头通知。配置WebHook时一定要设置Secret签名回调接收方校验签名后才能接受数据否则地址泄露之后任何人都能伪造事件。更进一步是接CI/CD流水线。Gitee提供了持续集成能力仓库根目录写好流水线配置文件每次push或PR都会触发云端构建和测试。有新人问本地测试不行吗本地测试只能保证“在我机器上能跑”流水线在干净环境里从零构建能抓出一堆本地缓存导致的假通过。我发现很多团队在Gitee上跑了几个月代码却从没配过自动流水线其实配好之后每次合并都在给主分支质量加一道保险。7. 权限模型与保护分支多人协作的最后一道防线7.1 成员角色怎么分只读、可写和可管理Gitee仓库的成员权限大体分为几个层级只读成员只能clone和查看可写成员能直接推送分支管理员能管理成员和仓库设置还有所有者拥有最高权限。实际分配的原则是最小权限能只读就不给写能写就不给管理。我们遇到过外包开发人员顺手把某个成员提成管理员的情况当时没当回事后来仓库规则被改得面目全非花了一下午才从日志里理清经过。新成员加入仓库时先想清楚他需要做什么只需要看代码的给只读需要在功能分支上开发的给可写需要管理保护分支和成员准入的才给管理员。账号权限宁可是事后追加不要一开始就慷慨放开。7.2 保护分支规则从“防止手滑”到“强制评审”没有保护分支的仓库最怕的不是有人恶意搞破坏而是有人“手滑”往master推了一堆没有评审过的代码。保护分支的价值在这里体现得最明显。Gitee设置里可以指定哪些分支受保护并启用一系列规则禁止直接推送、要求通过Pull Request合并、要求评审人通过、禁止强制推送。给主分支开启保护后所有改动都必须走PR这看起来增加了流程成本实际上把质量检查从“事后追责”变成了“事前拦截”。我们团队接管一个历史遗留项目时主分支没有任何保护发布前要人工排查每个人最近的提交后来开了保护分支并统一走PR两周之后主分支就稳定在一个可随时发布的状态。配置时建议把“禁止强制推送”一并打开。没有这个开关保护分支形同虚设因为任何人都可以用git push -f把历史覆盖掉。7.3 小团队与外包场景的权限分配参考不同协作形态权限模型差别很大。给一个参考配置角色类型权限建议说明技术负责人管理员管理成员、维护保护分支规则、负责最终合并一线开发可写成员能推送功能分支主分支靠PR合入测试/产品只读成员看代码、看Issue、不碰仓库内容外包开发Fork或指定分支可写隔离权限交付内容通过PR合入外包交付场景我特别推荐用Fork加PR的方式外包成员Fork主仓库到自己的账号下开发完跨仓库发起Pull Request技术负责人评审后合入。这样外包方始终不接触内部仓库的管理设置连直接推送功能分支的权限都可以省掉。8. 一次新功能发布的全流程复盘从Issue到Tag8.1 场景设定与分支准备把前面所有环节串联起来看一个完整场景。假设某个后台管理系统需要新增“积分明细导出”功能两位开发加一位测试需求已经提了Issue编号#107。主分支是master开启了保护分支规则任何人都不能直接推送。开发者A从master切出功能分支git checkout master git pull git checkout -b feature/point-export在分支上实现功能提交信息写清楚模块和改动点并在信息里写上关联Issue编号feat(point): 新增积分明细导出 - 后端新增导出接口 - 前端增加导出按钮与下载进度 - 覆盖导出数据量大于10万条的测试 关联 #1078.2 从提交到PR合并再到自动部署推送分支到远程之后在Gitee页面创建Pull Request目标分支选master描述里贴上述模板内容指定开发者B为评审人。B在PR页面逐行检查diff看到导出接口的日期格式化方式有问题在对应代码行留了一条评论。A看到后修复追加提交PR自动更新。B确认改动没问题同意合并。合入方式选squashmaster历史里多了一条干净的提交记录。这一切完成的同时WebHook已经把“PR已合并”事件推给了群机器人测试人员的群里出现一条消息master有新提交等待自动部署。仓库配置的CI流水线检测到push事件自动构建、跑测试、部署到测试环境。整个过程中没有任何人需要手动拷贝文件也没有人需要在群里喊“代码合了谁去布一下”。8.3 我们实际踩过的三个问题第一个问题是远程分支清理。有一段时间合完PR大家都不记得删除远程功能分支时间一长仓库里躺了几十个干枯分支。后来约定谁合入PR谁负责删除对应远程分支。Gitee界面有删除按钮合入后顺手点一下半秒钟的事。第二个问题是评审只看了代码逻辑没看配置变更。有一次某位开发在功能分支里修改了测试环境的数据库连接配置从代码角度看完全合理评审者也没注意到合入master后测试环境与开发环境配置打架。后来PR描述模板里加了“影响范围”栏凡是改配置文件必须在PR描述里列出来评审人单独确认。第三个问题有点反直觉保护分支一开始被质疑流程太繁琐。后来发现正因为主分支只能靠PR合入每个人的改动都经过了另一位成员的眼睛低级错误在合入前就被拦截返工次数明显下降。繁琐是感知层面的稳定是结果层面的跑了两个月以后团队里再没人提“要不开个例外直接推”。8.4 如果只能带走三条经验最后说几条压箱底的经验。第一先把保护分支和PR评审跑起来哪怕团队只有两个人两条命的互相检查好过一条命裸奔。第二提交信息规范越早统一越好历史记录是团队唯一无法重写的档案越整洁越值钱。第三WebHook加群机器人是投入产出比最高的自动化几分钟配完每天能省下大量“顺手通知一下”的沟通成本。至于更深度的Gitee用法流水线、Pages、Fork协作都属于在基础流程稳定之后逐渐加装的能力。先把代码托管、分支协作、PR评审这三件事做扎实Gitee作为国内开发者的代码托管与协作平台才能真正成为团队的日常标配。
如果你的日常工作流还停留在“把Gitee当成免费网盘clone下来push上去就完事”那你可能只用了这个代码托管平台一半以上的能力。我在过去几年带过好几个小团队从最开始互相clone压缩包传文件到后来把需求管理、代码评审、自动构建全部跑在Gitee上最大的感受是Gitee不只是存代码的地方它围绕代码托管延伸出的协作能力完全能撑起一个中小型团队的项目中枢。这篇分享我就从注册账号、配置SSH开始一路讲到分支策略、Pull Request评审、保护分支和自动化触发希望能帮你把Gitee真正用成“团队协作神器”。这套内容适合两类人一类是刚接触代码托管的新手照着步骤走就能把仓库跑起来另一类是用Gitee但只用基础功能的老用户可以顺手把当前工作流里缺失的环节补上。1. 为什么我把团队主力仓库迁到了Gitee1.1 国内网络的现实问题时快时慢的连接体验早期我们团队一度把仓库放在海外托管平台日常用起来最头疼的就是速度。你以为这只是“慢一点”的问题实际上全量clone一个几百MB、包含完整历史的仓库时经常卡在某个对象的解压阶段半小时后整个目录消失只能重来。团队成员分布在不同城市有人拉取五分钟有人拉取半小时每次新人入职光clone代码和环境准备就能耗掉一上午。把主力仓库迁到Gitee之后这种现象基本消失了。服务器在国内网络路径短大仓库的clone和push都能稳定跑完。对于需要频繁拉取最新代码、一天可能要操作几十次的场景这个稳定性比任何花哨功能都重要。后来我们总结出一个判断标准如果一个操作会让团队等超过十秒那这个操作每天重复一百次消耗的就是生产力。1.2 Gitee与海外托管平台的差异对比很多人以为国内外的代码托管平台只是“换了个皮肤”实际差异比想象中大。我按日常使用频率做了一个粗略对比维度Gitee海外平台(GitHub等)访问速度国内节点拉取推送稳定海外节点访问时快时慢私有仓库个人和团队私有仓库免费额度友好免费私有仓库面向小团队限制不少中文界面原生中文文档齐全中文是翻译版部分术语不一致社区生态国内开发者活跃中文讨论多国际开源项目更集中CI/CD提供Gitee Go等自动化流水线有成熟的Actions体系静态站点Gitee Pages可用有Pages但国内访问不稳定合规与数据数据存放在境内容易满足内部要求数据存放在境外敏感项目要掂量这里不是要分个高下而是说明选择的逻辑如果你服务的主要用户在国内团队开发主力也在国内那平台本身的访问稳定性就是第一优先级。开源项目做国际推广自然可以把海外平台作为主阵地内部业务系统、外包交付、课程Demo放在Gitee明显更顺手。1.3 什么样的仓库适合放Gitee什么样的不适合结合我们的迁移经验适合放Gitee的主要有三类第一类是内部业务系统代码不对外公开、又不想被海外网络拖慢私有仓库免费这个特性非常实用第二类是外包交付项目需要把代码托管、Issue记录、版本发布放在一起方便跟甲方对账第三类是课程教学和个人练手Demo中文界面和国内访问速度大大降低了新手的学习成本。不适合或者需要谨慎的是那些高度依赖海外开源生态的大型公共开源项目。这种项目的贡献者分布在全世界PR和Issue的协作节奏必须考虑国际时区强行把主仓库放国内反而增加参与门槛。常见的做法是主仓库留在海外在Gitee上开一个镜像仓库方便国内用户拉取代码、提交Issue。镜像同步属于平台提供的常规功能配置一次之后两边代码会自动保持一致。2. 账号准备与SSH配置把协作的地基先打好2.1 注册、实名与团队用户名约定Gitee注册没什么门槛手机号加邮箱就能完成。这里说两个容易被忽略的点。第一实名认证要早做。Gitee的Pages功能、部分企业级能力会要求实名等你想用的时候再认证会卡住发布时间。个人实名只需要在账号设置里按流程走一遍几分钟的事不要拖到项目上线前一天才想起来。第二用户名要提前统一。团队里我的做法是要求所有人的Gitee用户名和常用社交账号保持一致不许用“dev_001”这种编号。因为代码评审时协作者第一眼看到的是用户名如果每个人都是随机字符根本分不清这条评论是谁留的。用户名就是你在协作场景里的身份ID越可读越好。2.2 生成SSH Key并添加公钥五分钟做完的事推荐用SSH方式访问Gitee仓库免去每次输入密码也更安全。生成密钥的命令很简单ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车即可默认会在~/.ssh/下生成id_ed25519私钥和id_ed25519.pub公钥。然后查看公钥内容cat ~/.ssh/id_ed25519.pub复制整段公钥打开Gitee页面右上角头像 → 设置 → 安全设置 → SSH公钥 → 添加公钥粘贴保存。验证是否配置成功ssh -T gitgitee.com首次连接会提示确认主机指纹输入yes回车。如果配置成功会返回一条表示验证通过的信息。这里有个新手常见问题公钥添加后仍然报Permission denied (publickey)。八成是粘贴公钥时少了前缀或后缀或者用的是另一台机器的公钥。如果公司电脑和家里电脑都要推送两台机器要各自生成并添加公钥Gitee允许同一账号绑定多把公钥全部加进去就行。2.3 SSH和HTTPS怎么选以及两三件必须注意的小事HTTPS方式clone时不需要提前配SSH Key适合一次性下载代码。但每次push大概率要输入用户名密码除非在Git配置里缓存凭据。日常开发建议优先SSH配置一次之后所有操作都不需要反复认证。还有几个小细节值得注意。第一全局Git身份要设置好否则提交记录会显示成无名用户git config --global user.name 你的用户名 git config --global user.email 你的邮箱example.com这里的名字和邮箱最好与Gitee账号保持一致。这样提交历史能正确关联到账号代码评审时点击提交人就能跳到对应主页。第二Windows和macOS混用的团队换行符会自动转换建议在Windows侧执行git config --global core.autocrlf truemacOS/Linux侧保持默认避免每次pull都出现“整个文件被修改”的假diff。3. 建仓的几种常规路线与初始化规范3.1 网页端新建仓库模板和许可证怎么勾网页端新建仓库是最直观的方式。在Gitee首页点“新建仓库”填写仓库名称和路径选择公开还是私有然后会看到三个选项初始化仓库、添加README、添加.gitignore。新手容易忽略的是.gitignore。不选这个模板的话本地一堆编译产物、IDE配置文件会被一并提交上去仓库很快变得脏乱。Gitee提供了Java、Python、Node、Go等常用语言的模板新建时按项目语言选一个即可。即便忘了选之后把模板文件补进仓库也能生效。开源许可证方面如果仓库要对外开源推荐MIT或Apache-2.0。MIT足够简短适合不纠结细节的团队Apache-2.0多了专利授权条款适合企业背景的开源项目。内部私有项目不需要许可证选“无”就行。3.2 把本地已有项目推上Gitee从init到push很多时候我们不是从空仓库起步而是本地已经写了一堆代码。这时采用“先有本地仓库再关联远程”的路线git init git add . git commit -m chore: initial commit git remote add origin gitgitee.com:用户名/仓库名.git git push -u origin master需要强调的是正式提交前务必检查是否有敏感信息混入。常见事故是把数据库密码、API密钥、本地配置文件传上仓库一旦push出去即便删掉也会留在历史记录里。所以第一次提交最好给仓库配置好.gitignore运行仓库路径与URL扫描工具跑一遍再执行add和commit。3.3 从其他平台迁移仓库完整保留分支与Tag历史从海外平台迁回Gitee或是反向迁移最怕丢历史。推荐用裸仓库加镜像推送的方式git clone --bare gitgitee.com:用户名/旧仓库.git cd 旧仓库.git git push --mirror gitgitee.com:用户名/新仓库.git--bare克隆的是不含工作区的完整仓库--mirror会把所有分支、标签、引用一次性推给新地址。实际验证下来这个方式能完整保留提交历史。但迁移不等于复制数据仓库的成员权限、分支保护、WebHook、CI配置都要重建一遍建议把迁移清单列好按项检查。4. 日常提交与撤销动作背后的分支策略4.1 提交信息规范让每一条历史都值得回看团队代码评审时最痛苦的事是看到一个commit message只写着“update”或“修改”。追溯问题时完全不知道这个提交改了什么、为什么改。我们后来统一用了社区成熟的提交信息约定简单说就是给提交分类打标签feat新功能fix修复Bugdocs只改文档refactor重构不改功能test增加测试chore构建、依赖等杂项一个典型提交长这样feat(order): 增加按日期的订单数量统计 - 新增日期分组查询接口 - 前端列表页增加筛选条件 - 补充单元测试 关联 #23Gitee会自动识别提交信息里的#23并关联对应Issue评审人点进去就能看到来龙去脉。我们对团队的要求是一个提交只做一件事逻辑独立的改动要拆开提交这样回滚时只需要精准撤回某个提交不会连累其他功能。4.2 常用分支模型与命名习惯单分支直接推master的做法在团队协作里走不远。我强烈建议所有改动都走功能分支主分支永远保持可发布状态。分支命名用前缀区分意图feature/订单导出新功能fix/登录超时缺陷修复release/v2.0.0发布准备docs/读我说明文档调整实际开发中从主分支切出功能分支开发完成后合回主分支删除远程功能分支。主分支名字是master还是main不重要重要的是整个团队统一。Gitee新建仓库时可以设置默认分支名建立仓库那一刻就要定好后面再切换会麻烦很多。4.3 撤销操作的三个层次以及已推送提交的正确回退方式git 撤销操作经常让新手失眠因为不同命令的后果差异很大。按影响范围从小到大排列命令作用适用场景git reset --soft只撤销commit保留暂存区和改动提交后发现message写错了git reset --mixed(默认)撤销commit和暂存保留工作区改动提交后发现漏了文件想重新整理git reset --hard全部丢弃连工作区改动一起清掉彻底放弃该提交慎用如果提交已经push到了远程而且团队其他人可能已经拉取过这时候千万不要用reset去回退再强制推送那样会覆盖别人的本地历史造成混乱。正确做法是生成一个反向提交git revert HEADgit revert会新增一个提交逻辑上等于“撤销上一次改动”但历史是向前走的所有人都能安全拉取。我们团队的原则很简单没推送过的提交随便reset推送过的提交一律revert。万一错误执行了git reset --hard还有最后一根救命稻草git reflog找到丢失提交之前的哈希值再用git reset --hard 哈希值恢复。我在一次误操作里靠这个方法救回过大半天的产出所以只要本地仓库打开过reflog误删提交多半还有救。4.4 推送被拒的常见场景与应急处理推送失败不一定是操作错误更多是协作状态不同步。最常见的是non-fast-forward意思是远程分支有本地没有的新提交。解决方式git pull --rebase origin 当前分支名rebase会把本地提交“搬”到远程提交之后提交历史保持线性比直接merge产生的分叉好看好读。遇到冲突就在rebase过程中逐个解决解决完再继续git add 冲突文件 git rebase --continue git push另一种被拒是因为触发了保护分支规则提示没有权限直接推送到该分支。这时候不要想着绕过规则应该把改动提交到专门的功能分支然后在Gitee上发起Pull Request走评审流程合入。还有一种情况是推送超大文件被平台拒绝一般单文件超过平台配额就会报错解决思路是引入Git LFS大文件存储把体积大的二进制文件托管到LFS仓库本身只保存指针。5. Pull Request评审从一个人提交到一群人把关5.1 一次标准PR从创建到合并的完整路径Gitee的Pull Request简称PR是代码评审的核心入口。一个标准流程是从主分支切出功能分支开发并提交代码推送功能分支到Gitee远程仓库在仓库页面上方进入“Pull Requests”点击新建选择源分支功能分支和目标分支主分支填写标题和描述关联相关Issue指定评审人点击创建评审人在PR页面查看diff、留下行内评论开发者根据意见追加提交提交会自动更新到PR评审通过后点击合并很多团队用了很久Gitee却完全没点开过Pull Requests这个入口等于把最值钱的协作机制闲置了。没有PR的代码合入就像是没人检查的工单直接上线问题由用户来发现成本高得多。5.2 让人愿意认真review的PR写法代码评审质量不取决于评审人多严格很大程度上取决于PR描述写得好不好。我们团队使用了固定模板新人照着填就行## 背景 为什么需要这个改动关联的Issue ## 改动内容 - 改动点1 - 改动点2 ## 影响范围 涉及哪些模块是否需要同步更新文档 ## 测试情况 - 已验证场景 - 未覆盖场景 ## 其他备注 部署注意事项、数据库变更等除此之外还有几条不成文规则一个PR只解决一个问题尽量控制在几百行以内超过一千行的PR评审人看到就头大评审判定很容易走马观花推送之前自己先把diff从头到尾过一遍减少明显的低级错误。把PR看作一次书面沟通写清楚的人往往能更快拿到合并许可。5.3 三种合并方式的选择merge、squash还是rebaseGitee提供多种PR合并方式选错了会让历史变得难以梳理。三种方式的差异合并方式历史效果适用场景Merge提交保留PR所有提交多一个merge提交想让主分支时间线保留真实全过程Squash合并把PR整体压缩成单个提交功能分支上的零碎提交没保留价值Rebase合并PR提交逐个重放到目标分支历史线性希望历史干净又想保留每次提交我们团队日常以squash为主功能分支上那些“fix typo”“补充测试”的中间状态没必要留在主干历史里压缩成一个完整提交最清爽。发布分支则用Merge提交让发布节点有明确的合并记录。不管选哪种只要全团队约定一致历史都不会太难读。5.4 冲突处理别慌先把目标分支拉进来PR合并时经常出现“有冲突无法合并”的提示这通常不是大问题只是目标分支在你开发期间有了新变化。常见做法是把目标分支合并到自己的功能分支在本地解决冲突再推送回来git checkout 功能分支 git fetch origin git merge origin/master # 冲突文件手动解决 git add . git commit git pushPR会自动更新冲突状态消失后就可以合入了。要减少冲突核心习惯是功能分支不要活太久两天以上的分支最好每天同步一次目标分支不要攒到最后一次性解决堆积的冲突。6. Issue、Wiki、Pages与自动化把仓库变成项目中枢6.1 Issue与里程碑需求、Bug和版本迭代的管理入口很多团队把Issue当成可有可无的便签实际它是需求管理的绝佳容器。我们团队在Gitee上维护了一套简单的Issue规范Bug类模板固定包含“环境信息”“复现步骤”“期望行为”“实际行为”需求类模板包含“用户故事”“验收标准”。创建Issue时打上标签——bug、feature、improvement——再挂到对应的里程碑一个迭代的目标立刻清晰起来。提交代码时在commit message里写#Issue编号代码评审和Issue就能双向关联。比如修复Issue #12的提交会在Issue页面显示出来评审人、测试人员点过去就能追踪修复过程。这个串联机制看起来简单却是让仓库从“代码堆”变成“项目管理工具”的关键一步。6.2 Wiki和Pages把文档和官网放在代码旁边Gitee仓库自带Wiki适合放README承载不了的长篇文档接口约定、部署手册、操作指引、架构说明。和README的分工是README是仓库门面让陌生人一分钟内知道项目是干什么的、怎么跑起来Wiki是文档库承载日常维护和协作过程中的完整资料。Gitee Pages可以基于仓库生成静态网站玩法和海外平台的GitHub Pages类似。个人博客、项目官网、产品介绍页都能直接托管。需要注意Pages一般要求完成实名认证每次更新代码之后需要重新构建发布不是push完秒生效所以发版流程中要给构建和审核预留时间。我们用Pages做过一个项目的在线文档站把README、Wiki、API文档集中到一个站点外部合作方访问起来比翻仓库方便得多。6.3 WebHooks与CI/CD提交之后自动触发最优美WebHook是Gitee向外部系统推送事件通知的通道。配置路径一般在仓库的管理设置里选择触发事件——比如push、PR创建、Tag推送——填写一个公网可访问的回调地址。代码一推送Gitee就把JSON数据发到这个地址。我们最常见的用途是对接群机器人push后群内自动出现提交摘要PR合并后自动提醒测试人员部署省掉大量“代码推了你去拉一下”的口头通知。配置WebHook时一定要设置Secret签名回调接收方校验签名后才能接受数据否则地址泄露之后任何人都能伪造事件。更进一步是接CI/CD流水线。Gitee提供了持续集成能力仓库根目录写好流水线配置文件每次push或PR都会触发云端构建和测试。有新人问本地测试不行吗本地测试只能保证“在我机器上能跑”流水线在干净环境里从零构建能抓出一堆本地缓存导致的假通过。我发现很多团队在Gitee上跑了几个月代码却从没配过自动流水线其实配好之后每次合并都在给主分支质量加一道保险。7. 权限模型与保护分支多人协作的最后一道防线7.1 成员角色怎么分只读、可写和可管理Gitee仓库的成员权限大体分为几个层级只读成员只能clone和查看可写成员能直接推送分支管理员能管理成员和仓库设置还有所有者拥有最高权限。实际分配的原则是最小权限能只读就不给写能写就不给管理。我们遇到过外包开发人员顺手把某个成员提成管理员的情况当时没当回事后来仓库规则被改得面目全非花了一下午才从日志里理清经过。新成员加入仓库时先想清楚他需要做什么只需要看代码的给只读需要在功能分支上开发的给可写需要管理保护分支和成员准入的才给管理员。账号权限宁可是事后追加不要一开始就慷慨放开。7.2 保护分支规则从“防止手滑”到“强制评审”没有保护分支的仓库最怕的不是有人恶意搞破坏而是有人“手滑”往master推了一堆没有评审过的代码。保护分支的价值在这里体现得最明显。Gitee设置里可以指定哪些分支受保护并启用一系列规则禁止直接推送、要求通过Pull Request合并、要求评审人通过、禁止强制推送。给主分支开启保护后所有改动都必须走PR这看起来增加了流程成本实际上把质量检查从“事后追责”变成了“事前拦截”。我们团队接管一个历史遗留项目时主分支没有任何保护发布前要人工排查每个人最近的提交后来开了保护分支并统一走PR两周之后主分支就稳定在一个可随时发布的状态。配置时建议把“禁止强制推送”一并打开。没有这个开关保护分支形同虚设因为任何人都可以用git push -f把历史覆盖掉。7.3 小团队与外包场景的权限分配参考不同协作形态权限模型差别很大。给一个参考配置角色类型权限建议说明技术负责人管理员管理成员、维护保护分支规则、负责最终合并一线开发可写成员能推送功能分支主分支靠PR合入测试/产品只读成员看代码、看Issue、不碰仓库内容外包开发Fork或指定分支可写隔离权限交付内容通过PR合入外包交付场景我特别推荐用Fork加PR的方式外包成员Fork主仓库到自己的账号下开发完跨仓库发起Pull Request技术负责人评审后合入。这样外包方始终不接触内部仓库的管理设置连直接推送功能分支的权限都可以省掉。8. 一次新功能发布的全流程复盘从Issue到Tag8.1 场景设定与分支准备把前面所有环节串联起来看一个完整场景。假设某个后台管理系统需要新增“积分明细导出”功能两位开发加一位测试需求已经提了Issue编号#107。主分支是master开启了保护分支规则任何人都不能直接推送。开发者A从master切出功能分支git checkout master git pull git checkout -b feature/point-export在分支上实现功能提交信息写清楚模块和改动点并在信息里写上关联Issue编号feat(point): 新增积分明细导出 - 后端新增导出接口 - 前端增加导出按钮与下载进度 - 覆盖导出数据量大于10万条的测试 关联 #1078.2 从提交到PR合并再到自动部署推送分支到远程之后在Gitee页面创建Pull Request目标分支选master描述里贴上述模板内容指定开发者B为评审人。B在PR页面逐行检查diff看到导出接口的日期格式化方式有问题在对应代码行留了一条评论。A看到后修复追加提交PR自动更新。B确认改动没问题同意合并。合入方式选squashmaster历史里多了一条干净的提交记录。这一切完成的同时WebHook已经把“PR已合并”事件推给了群机器人测试人员的群里出现一条消息master有新提交等待自动部署。仓库配置的CI流水线检测到push事件自动构建、跑测试、部署到测试环境。整个过程中没有任何人需要手动拷贝文件也没有人需要在群里喊“代码合了谁去布一下”。8.3 我们实际踩过的三个问题第一个问题是远程分支清理。有一段时间合完PR大家都不记得删除远程功能分支时间一长仓库里躺了几十个干枯分支。后来约定谁合入PR谁负责删除对应远程分支。Gitee界面有删除按钮合入后顺手点一下半秒钟的事。第二个问题是评审只看了代码逻辑没看配置变更。有一次某位开发在功能分支里修改了测试环境的数据库连接配置从代码角度看完全合理评审者也没注意到合入master后测试环境与开发环境配置打架。后来PR描述模板里加了“影响范围”栏凡是改配置文件必须在PR描述里列出来评审人单独确认。第三个问题有点反直觉保护分支一开始被质疑流程太繁琐。后来发现正因为主分支只能靠PR合入每个人的改动都经过了另一位成员的眼睛低级错误在合入前就被拦截返工次数明显下降。繁琐是感知层面的稳定是结果层面的跑了两个月以后团队里再没人提“要不开个例外直接推”。8.4 如果只能带走三条经验最后说几条压箱底的经验。第一先把保护分支和PR评审跑起来哪怕团队只有两个人两条命的互相检查好过一条命裸奔。第二提交信息规范越早统一越好历史记录是团队唯一无法重写的档案越整洁越值钱。第三WebHook加群机器人是投入产出比最高的自动化几分钟配完每天能省下大量“顺手通知一下”的沟通成本。至于更深度的Gitee用法流水线、Pages、Fork协作都属于在基础流程稳定之后逐渐加装的能力。先把代码托管、分支协作、PR评审这三件事做扎实Gitee作为国内开发者的代码托管与协作平台才能真正成为团队的日常标配。
