1. 报名之前先想清楚你要的是一个仓库还是一条协作链路很多人看到代码协同开发体验活动这几个字第一反应是点进去建个仓库、提交两行代码、看看界面长得顺不顺眼然后关掉页面心想哦跟别的代码托管平台差不多。这种打开方式基本等于白跑一趟。我在几年前第一次接触这类平台体验活动时也这么干过结果三个月后团队真要迁移才发现当初那一圈点击什么有效信息都没留下。CodeArts Repo 这类平台提供的核心能力说到底是把代码托管、分支协作、代码评审、流水线触发、权限审计这几件事缝在一条链路上。单看任何一环市场上的选择都不少真正拉开差距的是这条链路上环节之间的衔接成本——评审能不能强制、合并能不能自动触发构建、权限能不能细到目录、审计日志能不能查清谁在什么时候动了哪个保护分支。这些东西你不带着真实场景去跑是看不出来的。所以这篇东西不打算写成功能罗列。我想聊的是如果你打算花几个小时参加这么一次体验活动怎么把时间用在刀刃上——怎么在活动环境里把一条完整的协同链路跑通怎么提前把迁移时会撞上的坑踩掉以及那些配置项背后到底在约束什么。适合准备做代码平台选型的技术负责人、刚接手团队仓库的维护者也适合单纯想把自己那摊子代码管得更规范的个人开发者。1.1 把团队的痛写成一张可验证的清单体验活动最大的陷阱是演示数据陷阱你在一个空仓库里随手提交几个文件所有功能都顺滑得像广告。真实团队不是这样的。真实团队有历史包袱、有几百兆的二进制文件、有五个人的提交习惯各不相同。我建议在报名之前先花二十分钟把当前协作里最疼的三到五件事写成清单每一条都要能对应一个可验证的动作。比如新人入职第一天要花半天配环境对应的验证动作是让一个没接触过这个仓库的人只依靠仓库里的文档和凭据说明把代码拉下来并跑起来计时。再比如上线包是谁打的没人说得清对应的验证动作是翻一次两周前的发布看能不能在平台上查到触发构建的那个提交和那个人。这张清单不需要多漂亮但必须具体。下面这张表是我自己用的模板你可以直接改成自己的版本痛点描述在当前平台上的表现在体验环境里的验证动作判断通过的标准新人拉代码要折腾半天凭据文档过期、密钥格式不对用全新设备走一遍 SSH 配置十分钟内完成首次克隆评审流于形式能直接推主干没人拦尝试直接推送保护分支被拒绝并提示走合并请求合并后编译挂了没有合并前自动检查提交一个故意编译不过的分支合并按钮处于不可用状态权限给得太粗所有人都是管理员用只读账号尝试改配置操作被拒绝且有审计记录这张表填完你就知道自己该在体验活动里重点看什么了而不是被引导着一路点下一步。1.2 别在体验环境里堆垃圾数据另一个常见错误是拿真实仓库直接往里灌。听起来很务实实际上有两个问题一是数据合规真实业务代码进第三方环境要走审批很多团队卡在这一步二是真实仓库往往体积巨大导入一次要等很久把宝贵的体验时间全耗在进度条上。我的做法是造一个结构真实、内容脱敏的模拟仓库。具体来说保留目录层级和文件数量级比如五六个顶层模块、三百来个文件把业务逻辑替换成占位实现但故意保留几个真实存在的麻烦——一个 40MB 的资源文件、一段带 Windows 行尾的历史提交、两个已经废弃但还在被引用的子模块。这个仓库只有几十兆导入很快但它能暴露的问题和真实仓库八九不离十。提示模拟仓库一定要包含历史提交而不是一次性初始提交。很多平台的问题恰恰出在处理历史作者邮箱映射、处理奇怪的分支名、处理已经删除的标签上全新仓库测不出来。1.3 判断标准不要看功能列表长短平台对比时最容易犯的错是数功能。A 平台有二十项B 平台有十八项所以 A 更好——这个逻辑在代码托管领域基本失效。真正影响日常体验的往往是很朴素的三件事克隆和拉取的速度稳不稳定、评审流程能不能做成强制约束而不是君子协定、权限粒度能不能切到这个目录只允许这两个人改。速度这件事特别值得单独测。我的测法是在活动环境里挑一个中等规模仓库几千个提交分别在工作日的上午和晚上各做一次完整克隆记录耗时。如果两次差距超过一倍说明底层资源调度有问题后面团队几十号人天天拉代码会被这件事折磨。这个测试花不了几分钟但信息量比看十页产品介绍都大。2. 仓库落地的第一公里导入、凭据与那些会把历史带歪的设置把代码从旧地方搬到新地方听起来是个体力活实际上是个精细活。我见过太多团队在这一步图省事直接下载个压缩包再解压上传结果三年的提交历史、分支、标签全没了代码评审记录一条不剩。等半年后想追溯这行代码为什么这么写发现只能靠猜。2.1 导入现有仓库时历史提交比代码本身更值钱正确的做法是镜像克隆再推送。镜像克隆会把所有分支、所有标签、所有引用原样搬过来而不是只搬当前分支的工作区。命令本身很简单# 从旧地址做一次完整镜像克隆 git clone --mirror https://old-host/team/project.git project.git cd project.git # 推送到新仓库地址此时是裸仓库没有工作区 git push --mirror https://new-host/team/project.git这两行之后的坑才是重点。第一个坑是作者映射旧仓库里的提交作者可能是zhangsanold-company这种已经不存在的邮箱导入后平台上显示的作者是一串 ID 而不是人名贡献统计全乱。大部分平台在导入时会提供作者映射表把旧邮箱映射到新账号这件事必须在上线前一次性做完事后补极其痛苦要改写历史。第二个坑是大文件。Git 对文本友好对二进制不友好。如果你的仓库里躺着一个 200MB 的设计稿它会被完整复制进历史之后每一次克隆都要把这 200MB 拉一遍永远删不掉——因为历史不可变。这种情况要么用 Git LFS 把大文件挪出去要么用历史重写工具把那个文件从所有提交里剔除。前者适合以后还会有大文件的场景后者适合就这一次赶紧清掉。注意历史重写会改变所有提交的哈希值所有已克隆的副本都会失效。做这件事之前必须全员通知、全员停推做完之后所有人重新克隆。我见过一个团队在周五下午偷偷做这件事结果周一早上十几个人在推代码时全部冲突场面相当混乱。2.2 SSH 与 HTTPS 的取舍不是口味问题凭据配置这件小事能决定新人入职第一天的心情。SSH 和 HTTPS 两条路各有适用面SSH 适合长期使用的开发机配一次密钥管很久HTTPS 适合临时环境、CI 流水线、容器内部因为可以直接用访问令牌而不是私钥。SSH 这边最容易被忽略的是多账号共存。一个人同时有个人账号和团队账号两个密钥默认的~/.ssh/id_rsa只能对上一个。解决办法是写配置文件按主机名分流# ~/.ssh/config Host team-repo HostName repo.example.internal User git IdentityFile ~/.ssh/id_ed25519_team IdentitiesOnly yes然后克隆地址写成gitteam-repo:group/project.git这种别名形式。IdentitiesOnly yes这一行很关键不加的话 SSH 会把本机所有密钥挨个试一遍某些服务器在尝试次数超限后会直接拒绝连接症状是密钥明明是对的却连不上非常迷惑。HTTPS 这边要注意的是凭据缓存策略。把令牌明文写进远程地址https://user:tokenhost/...是最省事也最危险的做法——它会出现在.git/config里会出现在 shell 历史里会出现在同事帮你排查问题时你截的图里。稳妥一点的做法是用凭据助手把令牌存在系统密钥链里租期到了自动失效。2.3 三个配置文件决定后面半年会不会天天解冲突仓库根目录下有三个文件新项目十有八九没人建建了也没人看。但它们能省掉的麻烦抵得上一整天的排查时间。第一个是.gitattributes管行尾符。Windows 上是 CRLFLinux 和 macOS 是 LF。如果仓库里没有统一约定一个 Windows 同事提交文件后所有行尾都变了git diff显示整个文件全红全绿实际内容一个字没改。评审的人看到几千行变更直接放弃真正的逻辑改动就藏在这堆噪音里。解决办法是# .gitattributes * textauto eollf *.png binary *.xlsx binary *.bat text eolcrlf* textauto让 Git 自动识别文本文件并在仓库里统一存 LF检出时按平台转换。二进制文件要显式标记否则 Git 会尝试对它们做行尾转换结果就是文件损坏。第二个是.gitignore管什么东西不该进来。编译产物、依赖目录、本地配置、日志、IDE 的隐藏文件夹。这件事的价值不在于省空间而在于避免我不小心提交了带本地数据库密码的配置文件这种事故。建议在模板基础上按团队情况补几条尤其是*.local、*.env、config/*.private.*这类命名模式。第三个是仓库的体积守门人。Git LFS 的跟踪规则要提前定别等仓库涨到 2GB 才想起来。我的经验是单个文件超过 5MB 就该考虑走 LFS超过 50MB 基本必须走 LFS超过 200MB 应该压根不进仓库。迁移前检查项具体动作不做会怎样历史完整性用镜像克隆推送核对提交数、分支数、标签数历史丢失无法追溯作者映射导入时统一映射旧邮箱到新账号贡献统计失真责任无法归属大文件扫一遍历史中最大的十个文件决定是否转 LFS仓库永久臃肿克隆越来越慢行尾符加.gitattributes并做一次全库规范化每次跨平台提交都产生海量伪变更敏感信息扫历史中是否出现过密钥、口令密钥已泄露且删不掉最后一行尤其要重视。密钥一旦进入提交历史就算你下一个提交把它删了它依然躺在历史里任何人克隆都能翻出来。这种情况的唯一正确处理方式是立刻去源头把这个密钥作废并换新然后才考虑清理历史。顺序不能反。3. 分支与保护规则让必须评审从口号变成硬约束我们要求代码必须评审后才能合并——这句话我在很多团队的白板上见过然后在同一个团队的仓库里看到有人直接推主干。要求写在文档里是没用的必须落成平台上的硬约束。这也是我在体验活动里最看重的一块这套约束能不能配得足够细配完之后能不能真的拦住人。3.1 分支模型选型先看发布节奏再看团队规模关于分支模型的争论可以吵一整天但落到实操判断依据其实只有两条你多久发一次版以及同时有多少人在同一个代码库上改东西。如果产品是持续部署、每天甚至每次合并都上线那主干开发trunk-based最合适所有人往主干合功能没做完就用开关藏在特性开关后面。这种模式的好处是冲突暴露得早、集成成本低代价是对自动化测试要求高主干的任何一次提交都必须是可发布的。如果产品是按版本发布、有明确的迭代周期和回归测试窗口那主干 发布分支 短生命周期特性分支更稳。特性分支活不过三天发布分支拉出来之后只接受修复不接受新功能。Git Flow 那套 develop、release、hotfix 全齐的模型说实话在大部分中小团队里是过度设计。分支一多合并路径就变成一张网谁合到谁、什么时候合全靠人记。我见过一个团队用完整 Git Flow结果一个 hotfix 同时在三个分支上改了三遍第三遍还改漏了一行。我的建议是五个人以下、日更节奏就用主干开发加短分支十人以上、有版本窗口就用主干加发布分支除非有非常明确的合规要求别碰完整 Git Flow。3.2 保护分支上那几个开关关掉一个就等于没有评审分支建好之后真正起作用的是保护规则。平台上的开关通常有七八个我挑最关键的四个说因为只要漏掉其中一个整套约束就会出现缺口。第一个禁止直接推送。这一条是基础中的基础。不开这个其他所有规则都白搭因为人可以绕过合并请求直接推。开了之后所有改动必须走合并请求。第二个要求至少 N 人批准。N 取 1 还是 2取决于改动的影响面。我的习惯是主干要求 1 人发布分支要求 2 人涉及权限、支付、数据删除这类敏感路径的目录通过 CODEOWNERS 指定必须由对应负责人批准。这里有个细节一定要开启新提交使已有批准失效否则会出现我批准了然后作者又推了三个提交批准依然有效的情况评审形同虚设。第三个要求流水线通过。光有人看是不够的人看不出的编译错误、单元测试失败、静态检查问题得让机器拦。这条开了之后合并按钮在检查通过前是灰的这个视觉反馈比任何流程文档都管用。第四个要求分支是最新的。这条容易被忽略。如果允许基于过期的目标分支合并就可能出现我本地测试通过合进去之后因为别人先合了一个不兼容的改动而挂掉。要求合并前先把目标分支合进来并重新跑检查能规避掉绝大部分这类问题。提示保护规则建议先在体验环境里用一个测试账号故意违规操作一次确认真的会被拦住。我遇到过保护规则只对普通成员生效、管理员可以绕过的情况这种配置等于没配。3.3 合并策略的后果squash、rebase、merge commit 各自会让历史长什么样这个选择没有对错但后果差别很大而且事后很难改。合并提交merge commit保留完整的拓扑结构能看出一个特性分支是从哪里分出去、中间有哪些提交、什么时候合回来。好处是信息完整坏处是主干历史图会变得很花而且git log里混着大量wipfix typo再改一下这种噪音提交。压缩合并squash把一个分支上的所有提交压成一个落到主干上。主干历史非常干净一个特性一个提交回滚特别方便。代价是丢失分支内部的细粒度提交如果某个特性做了一周、改了三十次最后只留下一条提交记录中途的试错过程就没了。对大部分业务团队来说这个代价可以接受因为没人真的会去翻三十条中间提交。变基合并rebase把分支上的提交逐个重放到目标分支顶端得到线性历史且保留了细粒度提交。看起来两全其美但有两个风险一是提交哈希全变如果分支已经被别人拉过会产生混乱二是如果合并过程中解决冲突时出错错误会被分摊到多个提交里比一次合并更难定位。我的默认选择是业务功能分支用压缩合并保持主干干净底层库或者需要精细追溯的仓库用变基合并发布分支往回合并到主干时用合并提交保留这是一个发布的边界。合并策略主干历史回滚粒度适用场景主要风险合并提交非线性拓扑完整按提交发布分支回合并主干历史噪音多压缩合并线性一特性一提交按特性业务功能开发丢失中间提交变基合并线性保留细粒度按提交底层库、工具链哈希变化引发混乱4. 把检查推到提交之前钩子、规范与流水线的分工流水线跑得慢根因往往不在流水线本身而在于太多本该在本地解决的问题被推到了服务端。一个格式不合规的分号、一个拼错的提交信息、一个忘删的调试打印都值得花三分钟排队等一次构建失败吗显然不值得。所以我把质量检查分成三层本地钩子管出门前照镜子提交信息规范管给自动化提供输入流水线管真正需要完整环境才能验证的事。4.1 本地钩子负责别让脏东西出门提交前钩子最实用的三个检查格式化、静态检查、敏感信息扫描。前两个是习惯问题第三个是安全问题。配置方式通常是引入一个钩子管理工具在项目初始化时自动装到.git/hooks下。这里有个团队协作的经典矛盾钩子是本地的不进版本库你怎么保证每个人都装了答案是两条腿走路——一是把安装脚本写进项目的依赖安装流程比如npm install之后自动执行二是在流水线上保留同样的检查作为兜底。指望百分之百的人都装钩子是不现实的总有人的环境有问题所以服务端必须有最后一道闸。敏感信息扫描特别值得单独说。我见过最典型的事故是某开发者本地调试时把数据库连接串硬编码进了配置文件提交前钩子没装直接推上去了。这个连接串在历史里躺了两周才被发现期间所有克隆过仓库的人都有。所以本地钩子扫描的意义不在于抓坏人而在于把发现时间从两周缩短到两秒。4.2 提交信息规范不是洁癖是自动化的输入很多人觉得提交信息格式要求是形式主义。我以前也这么想直到有一次要做变更日志发现历史提交里一半是fix三分之一是修改剩下的是.和111。这种历史你没法自动生成任何东西。约定式提交Conventional Commits的核心就一句话提交信息的第一行用类型(范围): 描述的格式类型从固定集合里选feat、fix、docs、refactor、test、chore 等。这么做的直接收益有三个可以根据feat和fix自动生成变更日志可以根据类型决定版本号是升主版本还是次版本可以在评审时一眼看出这个改动是功能还是修补。feat(order): 支持按时间段筛选订单 fix(auth): 修复令牌过期后未跳转登录页的问题 refactor(payment): 抽出支付渠道适配层配合一个提交信息校验钩子不合规的直接拒绝提交。我知道有人会嫌烦但相信我等到你需要回溯上个版本到底改了什么的时候这份规范会救你。4.3 流水线里最值得先加的三道关卡流水线配置这件事我建议从最小的可用集合开始别一上来就搞十几个阶段。最值得先加的是三道第一道编译与单元测试。这是底线编译不过就不该允许合并。这一道要尽量快控制在五分钟以内超了就没人愿意等。优化手段是缓存依赖、只跑受影响的模块、并行拆分测试集。第二道静态扫描。空指针风险、未处理的异常、明显的资源泄漏、硬编码凭据。这一道适合设成有严重问题才阻断一般问题只提示否则一上来几百条告警团队很快就会养成看见红点直接忽略的习惯等于没做。第三道构建产物。把可部署的包或镜像构建出来并存档。这一道的价值是验证这个提交真的能产出可运行的产物而不是在我本地能跑。# 通用结构示意具体语法按平台文档调整 stages: - verify - build verify: stage: verify steps: - run: npm ci --prefer-offline - run: npm run lint - run: npm run test:unit -- --coverage cache: key: deps-$CI_COMMIT_REF paths: - node_modules/ build: stage: build needs: [verify] steps: - run: npm run build - upload: dist/这里有个容易踩的细节缓存的 key 不要图省事用固定字符串。用固定 key 会导致所有分支共享同一份缓存A 分支装了新依赖B 分支校验和它对不上构建随机失败排查起来极其费劲。按分支或按锁文件哈希做 key稳得多。5. 权限这件事给大了出事给小了拖慢权限管理是那种平时没人关心、出事时才想起来的东西。给得太松一个误操作就能把保护分支删掉给得太紧改一行文档都要找管理员日常效率被拖垮。我见过两种极端一种是全员管理员理由是人少方便另一种是除了负责人全是只读理由是安全。前者迟早出事故后者迟早把人逼走。5.1 角色划分与实际映射大部分平台的角色模型大同小异一般分四档拥有者、维护者、开发者、报告者。关键是搞清楚每一档能做什么然后在团队里做映射。拥有者能改仓库设置、删仓库、改权限这档只应该给一到两个人而且必须是那种知道自己在干什么的人。维护者能管理分支、合并请求、标签适合技术负责人和资深开发。开发者能推分支、提合并请求应该是绝大多数人的默认角色。报告者只能看和提问题适合外部合作方、测试同学、产品经理。有个小技巧默认角色一定要设成开发者而不是报告者或者维护者。新成员加入时默认给最小可用权限需要更多再申请比默认给大权限事后收回要安全得多——因为事后收回这件事几乎永远不会发生。5.2 CODEOWNERS 与目录级权限角色是粗粒度的真正解决问题的是按路径授权。CODEOWNERS 文件用一行一条规则的方式声明某个目录或某类文件的改动必须由谁批准# 所有涉及部署的改动必须由运维负责人批准 /deploy/ ops-lead # 数据库迁移脚本必须由两个人中的任意一个批准 /db/migrations/ backend-lead dba # 公共组件改动影响面大要求架构组批准 /src/common/ arch-group这个机制的价值在于把谁懂这块变成谁能批准这块。一个前端同学改了个样式不需要拉后端负责人来评审但有人动了部署脚本就必须过运维这关。规则配好之后合并请求会自动带上必须的评审人不会出现提了没人看的情况。如果平台支持目录级权限而不只是评审要求那更值得用。比如把生产配置目录设成只有两个人可写其他人的合并请求必须由这两人代合。这比要求批准更硬因为它拦在推送层面。5.3 密钥泄露的处置顺序这件事必须写在团队手册里因为一旦发生人在慌乱中很容易做错顺序。正确顺序是立即作废密钥。去签发方那里把这个凭据吊销或轮换这是唯一能止血的操作。不管代码还在不在凭据先废掉。查使用记录。看这个凭据在有效期内有没有被非预期的来源使用过判断影响范围。清理仓库。把明文从当前代码里删掉改成从环境变量或密钥管理服务读取。评估是否重写历史。如果仓库是公开的或者克隆过的人很多历史里的密钥虽然有备份价值但已失效重写历史的收益不大、代价不小通常可以不做。如果是内部仓库且访问面可控可以考虑重写。最常见的错误是顺序颠倒先忙着删代码、改历史忘了去作废凭据。代码删了密钥还活着攻击者该用还是用。6. 实测踩坑录六个我以为没问题的地方下面这些都是我在真实环境里撞过的每一个当时都觉得这不可能会出问题然后出了问题。坑一大文件把仓库撑到没法克隆。表现是某个同事突然克隆失败了报超时。排查过程很绕先怀疑网络换了三个网络环境都一样再怀疑磁盘空间充足最后用体积分析工具扫了一遍发现历史里有个 300MB 的视频文件是半年前做演示时误提交的后来删了但历史还在。修复方式是历史重写加 LFS 迁移全团队重新克隆。教训是仓库体积要有定期巡检别等出事。坑二行尾符导致整个文件全变更。表现是一个只改了一行的提交评审界面显示三千行变更。原因是提交者的编辑器把整个文件的 CRLF 转成了 LF。修复是加.gitattributes并做一次全库规范化提交这一个提交确实会有大量变更但只此一次之后所有新提交都干净了。这个坑的隐蔽之处在于加完配置之后本地工作区需要重新检出才能真正生效很多人加完配置发现没变化就以为没用。坑三子模块指向了一个已经不存在的提交。表现是克隆之后构建失败报某个依赖目录为空。查下来是子模块的引用指向了上游仓库被强制推送后消失的提交。修复是把子模块更新到存在的提交上。根本性的教训是子模块的引用非常脆弱上游一旦重写历史就断。能用包管理器解决的依赖别用子模块非要用就在主仓库里锁定一个稳定标签而不是某个浮动提交。坑四强制推送覆盖了别人的工作。表现是同事说他推的三个提交不见了。原因是另一个人在自己分支上做了变基后强制推送而这个分支恰好是共享的。这个坑没有技术解法只有约定共享分支永远不强制推送要变基就在自己的私有分支做或者用--force-with-lease这个稍微安全一点的选项——它会在远程有你不知道的新提交时拒绝推送。坑五评审卡在等一个人回复。表现是一个紧急修复的合并请求挂了两天因为指定的评审人在休假。修复是在保护规则里配置评审组而不是具体某个人组里任意一人批准即可并设置超时自动升级提醒。规则设计时要考虑人的缺席这是很多流程设计的盲点。坑六钩子只在装了的人机器上生效。表现是同一个格式问题被反复提交有人说我本地明明检查过了因为他确实装了钩子但另外两个人没装。修复是把同样的检查逻辑搬到流水线上本地钩子只作为提前发现的便利不作为唯一防线。任何依赖客户端自觉的约束都不能当作安全边界。最后一个我自己摸索出来的小习惯每次在平台里配置完一项保护规则我都会用一个专门的测试账号去故意违反一次确认真的拦得住。这件事花不了一分钟但能避免那种以为配了其实没生效的情况。规则这东西只有被验证过才算数。
1. 报名之前先想清楚你要的是一个仓库还是一条协作链路很多人看到代码协同开发体验活动这几个字第一反应是点进去建个仓库、提交两行代码、看看界面长得顺不顺眼然后关掉页面心想哦跟别的代码托管平台差不多。这种打开方式基本等于白跑一趟。我在几年前第一次接触这类平台体验活动时也这么干过结果三个月后团队真要迁移才发现当初那一圈点击什么有效信息都没留下。CodeArts Repo 这类平台提供的核心能力说到底是把代码托管、分支协作、代码评审、流水线触发、权限审计这几件事缝在一条链路上。单看任何一环市场上的选择都不少真正拉开差距的是这条链路上环节之间的衔接成本——评审能不能强制、合并能不能自动触发构建、权限能不能细到目录、审计日志能不能查清谁在什么时候动了哪个保护分支。这些东西你不带着真实场景去跑是看不出来的。所以这篇东西不打算写成功能罗列。我想聊的是如果你打算花几个小时参加这么一次体验活动怎么把时间用在刀刃上——怎么在活动环境里把一条完整的协同链路跑通怎么提前把迁移时会撞上的坑踩掉以及那些配置项背后到底在约束什么。适合准备做代码平台选型的技术负责人、刚接手团队仓库的维护者也适合单纯想把自己那摊子代码管得更规范的个人开发者。1.1 把团队的痛写成一张可验证的清单体验活动最大的陷阱是演示数据陷阱你在一个空仓库里随手提交几个文件所有功能都顺滑得像广告。真实团队不是这样的。真实团队有历史包袱、有几百兆的二进制文件、有五个人的提交习惯各不相同。我建议在报名之前先花二十分钟把当前协作里最疼的三到五件事写成清单每一条都要能对应一个可验证的动作。比如新人入职第一天要花半天配环境对应的验证动作是让一个没接触过这个仓库的人只依靠仓库里的文档和凭据说明把代码拉下来并跑起来计时。再比如上线包是谁打的没人说得清对应的验证动作是翻一次两周前的发布看能不能在平台上查到触发构建的那个提交和那个人。这张清单不需要多漂亮但必须具体。下面这张表是我自己用的模板你可以直接改成自己的版本痛点描述在当前平台上的表现在体验环境里的验证动作判断通过的标准新人拉代码要折腾半天凭据文档过期、密钥格式不对用全新设备走一遍 SSH 配置十分钟内完成首次克隆评审流于形式能直接推主干没人拦尝试直接推送保护分支被拒绝并提示走合并请求合并后编译挂了没有合并前自动检查提交一个故意编译不过的分支合并按钮处于不可用状态权限给得太粗所有人都是管理员用只读账号尝试改配置操作被拒绝且有审计记录这张表填完你就知道自己该在体验活动里重点看什么了而不是被引导着一路点下一步。1.2 别在体验环境里堆垃圾数据另一个常见错误是拿真实仓库直接往里灌。听起来很务实实际上有两个问题一是数据合规真实业务代码进第三方环境要走审批很多团队卡在这一步二是真实仓库往往体积巨大导入一次要等很久把宝贵的体验时间全耗在进度条上。我的做法是造一个结构真实、内容脱敏的模拟仓库。具体来说保留目录层级和文件数量级比如五六个顶层模块、三百来个文件把业务逻辑替换成占位实现但故意保留几个真实存在的麻烦——一个 40MB 的资源文件、一段带 Windows 行尾的历史提交、两个已经废弃但还在被引用的子模块。这个仓库只有几十兆导入很快但它能暴露的问题和真实仓库八九不离十。提示模拟仓库一定要包含历史提交而不是一次性初始提交。很多平台的问题恰恰出在处理历史作者邮箱映射、处理奇怪的分支名、处理已经删除的标签上全新仓库测不出来。1.3 判断标准不要看功能列表长短平台对比时最容易犯的错是数功能。A 平台有二十项B 平台有十八项所以 A 更好——这个逻辑在代码托管领域基本失效。真正影响日常体验的往往是很朴素的三件事克隆和拉取的速度稳不稳定、评审流程能不能做成强制约束而不是君子协定、权限粒度能不能切到这个目录只允许这两个人改。速度这件事特别值得单独测。我的测法是在活动环境里挑一个中等规模仓库几千个提交分别在工作日的上午和晚上各做一次完整克隆记录耗时。如果两次差距超过一倍说明底层资源调度有问题后面团队几十号人天天拉代码会被这件事折磨。这个测试花不了几分钟但信息量比看十页产品介绍都大。2. 仓库落地的第一公里导入、凭据与那些会把历史带歪的设置把代码从旧地方搬到新地方听起来是个体力活实际上是个精细活。我见过太多团队在这一步图省事直接下载个压缩包再解压上传结果三年的提交历史、分支、标签全没了代码评审记录一条不剩。等半年后想追溯这行代码为什么这么写发现只能靠猜。2.1 导入现有仓库时历史提交比代码本身更值钱正确的做法是镜像克隆再推送。镜像克隆会把所有分支、所有标签、所有引用原样搬过来而不是只搬当前分支的工作区。命令本身很简单# 从旧地址做一次完整镜像克隆 git clone --mirror https://old-host/team/project.git project.git cd project.git # 推送到新仓库地址此时是裸仓库没有工作区 git push --mirror https://new-host/team/project.git这两行之后的坑才是重点。第一个坑是作者映射旧仓库里的提交作者可能是zhangsanold-company这种已经不存在的邮箱导入后平台上显示的作者是一串 ID 而不是人名贡献统计全乱。大部分平台在导入时会提供作者映射表把旧邮箱映射到新账号这件事必须在上线前一次性做完事后补极其痛苦要改写历史。第二个坑是大文件。Git 对文本友好对二进制不友好。如果你的仓库里躺着一个 200MB 的设计稿它会被完整复制进历史之后每一次克隆都要把这 200MB 拉一遍永远删不掉——因为历史不可变。这种情况要么用 Git LFS 把大文件挪出去要么用历史重写工具把那个文件从所有提交里剔除。前者适合以后还会有大文件的场景后者适合就这一次赶紧清掉。注意历史重写会改变所有提交的哈希值所有已克隆的副本都会失效。做这件事之前必须全员通知、全员停推做完之后所有人重新克隆。我见过一个团队在周五下午偷偷做这件事结果周一早上十几个人在推代码时全部冲突场面相当混乱。2.2 SSH 与 HTTPS 的取舍不是口味问题凭据配置这件小事能决定新人入职第一天的心情。SSH 和 HTTPS 两条路各有适用面SSH 适合长期使用的开发机配一次密钥管很久HTTPS 适合临时环境、CI 流水线、容器内部因为可以直接用访问令牌而不是私钥。SSH 这边最容易被忽略的是多账号共存。一个人同时有个人账号和团队账号两个密钥默认的~/.ssh/id_rsa只能对上一个。解决办法是写配置文件按主机名分流# ~/.ssh/config Host team-repo HostName repo.example.internal User git IdentityFile ~/.ssh/id_ed25519_team IdentitiesOnly yes然后克隆地址写成gitteam-repo:group/project.git这种别名形式。IdentitiesOnly yes这一行很关键不加的话 SSH 会把本机所有密钥挨个试一遍某些服务器在尝试次数超限后会直接拒绝连接症状是密钥明明是对的却连不上非常迷惑。HTTPS 这边要注意的是凭据缓存策略。把令牌明文写进远程地址https://user:tokenhost/...是最省事也最危险的做法——它会出现在.git/config里会出现在 shell 历史里会出现在同事帮你排查问题时你截的图里。稳妥一点的做法是用凭据助手把令牌存在系统密钥链里租期到了自动失效。2.3 三个配置文件决定后面半年会不会天天解冲突仓库根目录下有三个文件新项目十有八九没人建建了也没人看。但它们能省掉的麻烦抵得上一整天的排查时间。第一个是.gitattributes管行尾符。Windows 上是 CRLFLinux 和 macOS 是 LF。如果仓库里没有统一约定一个 Windows 同事提交文件后所有行尾都变了git diff显示整个文件全红全绿实际内容一个字没改。评审的人看到几千行变更直接放弃真正的逻辑改动就藏在这堆噪音里。解决办法是# .gitattributes * textauto eollf *.png binary *.xlsx binary *.bat text eolcrlf* textauto让 Git 自动识别文本文件并在仓库里统一存 LF检出时按平台转换。二进制文件要显式标记否则 Git 会尝试对它们做行尾转换结果就是文件损坏。第二个是.gitignore管什么东西不该进来。编译产物、依赖目录、本地配置、日志、IDE 的隐藏文件夹。这件事的价值不在于省空间而在于避免我不小心提交了带本地数据库密码的配置文件这种事故。建议在模板基础上按团队情况补几条尤其是*.local、*.env、config/*.private.*这类命名模式。第三个是仓库的体积守门人。Git LFS 的跟踪规则要提前定别等仓库涨到 2GB 才想起来。我的经验是单个文件超过 5MB 就该考虑走 LFS超过 50MB 基本必须走 LFS超过 200MB 应该压根不进仓库。迁移前检查项具体动作不做会怎样历史完整性用镜像克隆推送核对提交数、分支数、标签数历史丢失无法追溯作者映射导入时统一映射旧邮箱到新账号贡献统计失真责任无法归属大文件扫一遍历史中最大的十个文件决定是否转 LFS仓库永久臃肿克隆越来越慢行尾符加.gitattributes并做一次全库规范化每次跨平台提交都产生海量伪变更敏感信息扫历史中是否出现过密钥、口令密钥已泄露且删不掉最后一行尤其要重视。密钥一旦进入提交历史就算你下一个提交把它删了它依然躺在历史里任何人克隆都能翻出来。这种情况的唯一正确处理方式是立刻去源头把这个密钥作废并换新然后才考虑清理历史。顺序不能反。3. 分支与保护规则让必须评审从口号变成硬约束我们要求代码必须评审后才能合并——这句话我在很多团队的白板上见过然后在同一个团队的仓库里看到有人直接推主干。要求写在文档里是没用的必须落成平台上的硬约束。这也是我在体验活动里最看重的一块这套约束能不能配得足够细配完之后能不能真的拦住人。3.1 分支模型选型先看发布节奏再看团队规模关于分支模型的争论可以吵一整天但落到实操判断依据其实只有两条你多久发一次版以及同时有多少人在同一个代码库上改东西。如果产品是持续部署、每天甚至每次合并都上线那主干开发trunk-based最合适所有人往主干合功能没做完就用开关藏在特性开关后面。这种模式的好处是冲突暴露得早、集成成本低代价是对自动化测试要求高主干的任何一次提交都必须是可发布的。如果产品是按版本发布、有明确的迭代周期和回归测试窗口那主干 发布分支 短生命周期特性分支更稳。特性分支活不过三天发布分支拉出来之后只接受修复不接受新功能。Git Flow 那套 develop、release、hotfix 全齐的模型说实话在大部分中小团队里是过度设计。分支一多合并路径就变成一张网谁合到谁、什么时候合全靠人记。我见过一个团队用完整 Git Flow结果一个 hotfix 同时在三个分支上改了三遍第三遍还改漏了一行。我的建议是五个人以下、日更节奏就用主干开发加短分支十人以上、有版本窗口就用主干加发布分支除非有非常明确的合规要求别碰完整 Git Flow。3.2 保护分支上那几个开关关掉一个就等于没有评审分支建好之后真正起作用的是保护规则。平台上的开关通常有七八个我挑最关键的四个说因为只要漏掉其中一个整套约束就会出现缺口。第一个禁止直接推送。这一条是基础中的基础。不开这个其他所有规则都白搭因为人可以绕过合并请求直接推。开了之后所有改动必须走合并请求。第二个要求至少 N 人批准。N 取 1 还是 2取决于改动的影响面。我的习惯是主干要求 1 人发布分支要求 2 人涉及权限、支付、数据删除这类敏感路径的目录通过 CODEOWNERS 指定必须由对应负责人批准。这里有个细节一定要开启新提交使已有批准失效否则会出现我批准了然后作者又推了三个提交批准依然有效的情况评审形同虚设。第三个要求流水线通过。光有人看是不够的人看不出的编译错误、单元测试失败、静态检查问题得让机器拦。这条开了之后合并按钮在检查通过前是灰的这个视觉反馈比任何流程文档都管用。第四个要求分支是最新的。这条容易被忽略。如果允许基于过期的目标分支合并就可能出现我本地测试通过合进去之后因为别人先合了一个不兼容的改动而挂掉。要求合并前先把目标分支合进来并重新跑检查能规避掉绝大部分这类问题。提示保护规则建议先在体验环境里用一个测试账号故意违规操作一次确认真的会被拦住。我遇到过保护规则只对普通成员生效、管理员可以绕过的情况这种配置等于没配。3.3 合并策略的后果squash、rebase、merge commit 各自会让历史长什么样这个选择没有对错但后果差别很大而且事后很难改。合并提交merge commit保留完整的拓扑结构能看出一个特性分支是从哪里分出去、中间有哪些提交、什么时候合回来。好处是信息完整坏处是主干历史图会变得很花而且git log里混着大量wipfix typo再改一下这种噪音提交。压缩合并squash把一个分支上的所有提交压成一个落到主干上。主干历史非常干净一个特性一个提交回滚特别方便。代价是丢失分支内部的细粒度提交如果某个特性做了一周、改了三十次最后只留下一条提交记录中途的试错过程就没了。对大部分业务团队来说这个代价可以接受因为没人真的会去翻三十条中间提交。变基合并rebase把分支上的提交逐个重放到目标分支顶端得到线性历史且保留了细粒度提交。看起来两全其美但有两个风险一是提交哈希全变如果分支已经被别人拉过会产生混乱二是如果合并过程中解决冲突时出错错误会被分摊到多个提交里比一次合并更难定位。我的默认选择是业务功能分支用压缩合并保持主干干净底层库或者需要精细追溯的仓库用变基合并发布分支往回合并到主干时用合并提交保留这是一个发布的边界。合并策略主干历史回滚粒度适用场景主要风险合并提交非线性拓扑完整按提交发布分支回合并主干历史噪音多压缩合并线性一特性一提交按特性业务功能开发丢失中间提交变基合并线性保留细粒度按提交底层库、工具链哈希变化引发混乱4. 把检查推到提交之前钩子、规范与流水线的分工流水线跑得慢根因往往不在流水线本身而在于太多本该在本地解决的问题被推到了服务端。一个格式不合规的分号、一个拼错的提交信息、一个忘删的调试打印都值得花三分钟排队等一次构建失败吗显然不值得。所以我把质量检查分成三层本地钩子管出门前照镜子提交信息规范管给自动化提供输入流水线管真正需要完整环境才能验证的事。4.1 本地钩子负责别让脏东西出门提交前钩子最实用的三个检查格式化、静态检查、敏感信息扫描。前两个是习惯问题第三个是安全问题。配置方式通常是引入一个钩子管理工具在项目初始化时自动装到.git/hooks下。这里有个团队协作的经典矛盾钩子是本地的不进版本库你怎么保证每个人都装了答案是两条腿走路——一是把安装脚本写进项目的依赖安装流程比如npm install之后自动执行二是在流水线上保留同样的检查作为兜底。指望百分之百的人都装钩子是不现实的总有人的环境有问题所以服务端必须有最后一道闸。敏感信息扫描特别值得单独说。我见过最典型的事故是某开发者本地调试时把数据库连接串硬编码进了配置文件提交前钩子没装直接推上去了。这个连接串在历史里躺了两周才被发现期间所有克隆过仓库的人都有。所以本地钩子扫描的意义不在于抓坏人而在于把发现时间从两周缩短到两秒。4.2 提交信息规范不是洁癖是自动化的输入很多人觉得提交信息格式要求是形式主义。我以前也这么想直到有一次要做变更日志发现历史提交里一半是fix三分之一是修改剩下的是.和111。这种历史你没法自动生成任何东西。约定式提交Conventional Commits的核心就一句话提交信息的第一行用类型(范围): 描述的格式类型从固定集合里选feat、fix、docs、refactor、test、chore 等。这么做的直接收益有三个可以根据feat和fix自动生成变更日志可以根据类型决定版本号是升主版本还是次版本可以在评审时一眼看出这个改动是功能还是修补。feat(order): 支持按时间段筛选订单 fix(auth): 修复令牌过期后未跳转登录页的问题 refactor(payment): 抽出支付渠道适配层配合一个提交信息校验钩子不合规的直接拒绝提交。我知道有人会嫌烦但相信我等到你需要回溯上个版本到底改了什么的时候这份规范会救你。4.3 流水线里最值得先加的三道关卡流水线配置这件事我建议从最小的可用集合开始别一上来就搞十几个阶段。最值得先加的是三道第一道编译与单元测试。这是底线编译不过就不该允许合并。这一道要尽量快控制在五分钟以内超了就没人愿意等。优化手段是缓存依赖、只跑受影响的模块、并行拆分测试集。第二道静态扫描。空指针风险、未处理的异常、明显的资源泄漏、硬编码凭据。这一道适合设成有严重问题才阻断一般问题只提示否则一上来几百条告警团队很快就会养成看见红点直接忽略的习惯等于没做。第三道构建产物。把可部署的包或镜像构建出来并存档。这一道的价值是验证这个提交真的能产出可运行的产物而不是在我本地能跑。# 通用结构示意具体语法按平台文档调整 stages: - verify - build verify: stage: verify steps: - run: npm ci --prefer-offline - run: npm run lint - run: npm run test:unit -- --coverage cache: key: deps-$CI_COMMIT_REF paths: - node_modules/ build: stage: build needs: [verify] steps: - run: npm run build - upload: dist/这里有个容易踩的细节缓存的 key 不要图省事用固定字符串。用固定 key 会导致所有分支共享同一份缓存A 分支装了新依赖B 分支校验和它对不上构建随机失败排查起来极其费劲。按分支或按锁文件哈希做 key稳得多。5. 权限这件事给大了出事给小了拖慢权限管理是那种平时没人关心、出事时才想起来的东西。给得太松一个误操作就能把保护分支删掉给得太紧改一行文档都要找管理员日常效率被拖垮。我见过两种极端一种是全员管理员理由是人少方便另一种是除了负责人全是只读理由是安全。前者迟早出事故后者迟早把人逼走。5.1 角色划分与实际映射大部分平台的角色模型大同小异一般分四档拥有者、维护者、开发者、报告者。关键是搞清楚每一档能做什么然后在团队里做映射。拥有者能改仓库设置、删仓库、改权限这档只应该给一到两个人而且必须是那种知道自己在干什么的人。维护者能管理分支、合并请求、标签适合技术负责人和资深开发。开发者能推分支、提合并请求应该是绝大多数人的默认角色。报告者只能看和提问题适合外部合作方、测试同学、产品经理。有个小技巧默认角色一定要设成开发者而不是报告者或者维护者。新成员加入时默认给最小可用权限需要更多再申请比默认给大权限事后收回要安全得多——因为事后收回这件事几乎永远不会发生。5.2 CODEOWNERS 与目录级权限角色是粗粒度的真正解决问题的是按路径授权。CODEOWNERS 文件用一行一条规则的方式声明某个目录或某类文件的改动必须由谁批准# 所有涉及部署的改动必须由运维负责人批准 /deploy/ ops-lead # 数据库迁移脚本必须由两个人中的任意一个批准 /db/migrations/ backend-lead dba # 公共组件改动影响面大要求架构组批准 /src/common/ arch-group这个机制的价值在于把谁懂这块变成谁能批准这块。一个前端同学改了个样式不需要拉后端负责人来评审但有人动了部署脚本就必须过运维这关。规则配好之后合并请求会自动带上必须的评审人不会出现提了没人看的情况。如果平台支持目录级权限而不只是评审要求那更值得用。比如把生产配置目录设成只有两个人可写其他人的合并请求必须由这两人代合。这比要求批准更硬因为它拦在推送层面。5.3 密钥泄露的处置顺序这件事必须写在团队手册里因为一旦发生人在慌乱中很容易做错顺序。正确顺序是立即作废密钥。去签发方那里把这个凭据吊销或轮换这是唯一能止血的操作。不管代码还在不在凭据先废掉。查使用记录。看这个凭据在有效期内有没有被非预期的来源使用过判断影响范围。清理仓库。把明文从当前代码里删掉改成从环境变量或密钥管理服务读取。评估是否重写历史。如果仓库是公开的或者克隆过的人很多历史里的密钥虽然有备份价值但已失效重写历史的收益不大、代价不小通常可以不做。如果是内部仓库且访问面可控可以考虑重写。最常见的错误是顺序颠倒先忙着删代码、改历史忘了去作废凭据。代码删了密钥还活着攻击者该用还是用。6. 实测踩坑录六个我以为没问题的地方下面这些都是我在真实环境里撞过的每一个当时都觉得这不可能会出问题然后出了问题。坑一大文件把仓库撑到没法克隆。表现是某个同事突然克隆失败了报超时。排查过程很绕先怀疑网络换了三个网络环境都一样再怀疑磁盘空间充足最后用体积分析工具扫了一遍发现历史里有个 300MB 的视频文件是半年前做演示时误提交的后来删了但历史还在。修复方式是历史重写加 LFS 迁移全团队重新克隆。教训是仓库体积要有定期巡检别等出事。坑二行尾符导致整个文件全变更。表现是一个只改了一行的提交评审界面显示三千行变更。原因是提交者的编辑器把整个文件的 CRLF 转成了 LF。修复是加.gitattributes并做一次全库规范化提交这一个提交确实会有大量变更但只此一次之后所有新提交都干净了。这个坑的隐蔽之处在于加完配置之后本地工作区需要重新检出才能真正生效很多人加完配置发现没变化就以为没用。坑三子模块指向了一个已经不存在的提交。表现是克隆之后构建失败报某个依赖目录为空。查下来是子模块的引用指向了上游仓库被强制推送后消失的提交。修复是把子模块更新到存在的提交上。根本性的教训是子模块的引用非常脆弱上游一旦重写历史就断。能用包管理器解决的依赖别用子模块非要用就在主仓库里锁定一个稳定标签而不是某个浮动提交。坑四强制推送覆盖了别人的工作。表现是同事说他推的三个提交不见了。原因是另一个人在自己分支上做了变基后强制推送而这个分支恰好是共享的。这个坑没有技术解法只有约定共享分支永远不强制推送要变基就在自己的私有分支做或者用--force-with-lease这个稍微安全一点的选项——它会在远程有你不知道的新提交时拒绝推送。坑五评审卡在等一个人回复。表现是一个紧急修复的合并请求挂了两天因为指定的评审人在休假。修复是在保护规则里配置评审组而不是具体某个人组里任意一人批准即可并设置超时自动升级提醒。规则设计时要考虑人的缺席这是很多流程设计的盲点。坑六钩子只在装了的人机器上生效。表现是同一个格式问题被反复提交有人说我本地明明检查过了因为他确实装了钩子但另外两个人没装。修复是把同样的检查逻辑搬到流水线上本地钩子只作为提前发现的便利不作为唯一防线。任何依赖客户端自觉的约束都不能当作安全边界。最后一个我自己摸索出来的小习惯每次在平台里配置完一项保护规则我都会用一个专门的测试账号去故意违反一次确认真的拦得住。这件事花不了一分钟但能避免那种以为配了其实没生效的情况。规则这东西只有被验证过才算数。
