CI 每个作业都在全量克隆,浅克隆与获取深度怎么配
CI 每个作业都在全量克隆,浅克隆与获取深度怎么配
定义:浅克隆(Shallow Clone)指 CI 作业获取代码时只拉取最近 N 次提交的仓库历史,而不是完整历史。在极狐GitLab 中通过项目级「Git 浅克隆」设置或
.gitlab-ci.yml中的GIT_DEPTH变量控制,两者可按作业粒度覆盖。
为什么流水线会被克隆拖慢
不少团队排查 CI 耗时的时候,眼睛都盯在构建和测试步骤上,却忽略了每个作业开始前的 git 获取阶段。仓库用了三五年,历史提交几万次、大文件来回进出过多次之后,一次全量克隆可能就是一两分钟——而流水线里每个作业都要各自走一遍这个流程。
假设一条流水线有 6 个作业,单次克隆多花 90 秒,一天跑 200 条流水线,光克隆就烧掉了近 20 个小时的无谓算力。更现实的问题是:绝大多数作业只关心最新一次提交的代码状态,比如跑 lint、跑单测、构建镜像,根本用不到三年前的历史。
按官方文档,新建项目的默认 git 深度值为 20,也就是只获取最近 20 次提交。但存量项目、迁移项目或者被改过配置的项目,很可能仍是全量获取。确认与调整,正是这篇文章要解决的问题。
怎么配获取深度
第一步,先看项目设置
进入项目 设置 → CI/CD → 通用流水线,找到两个关键配置:
Git 策略:决定作业是
fetch(增量获取,默认)还是clone(每次全新克隆);Git 浅克隆:填入克隆深度,例如
50,表示只获取最近 50 次提交。
对多数项目来说,把 Git 策略保持 fetch、深度设为 50 已经能覆盖绝大多数场景。
第二步,按作业粒度覆盖
项目设置是全局生效的,但有些作业需要更深的提交历史。.gitlab-ci.yml 中的变量可以覆盖项目设置:
build:
variables:
GIT_DEPTH: 100 # 本作业获取最近 100 次提交
script:
- mvn package
release-notes:
variables:
GIT_DEPTH: 0 # 0 表示不做浅克隆,获取完整历史
GIT_STRATEGY: clone # 本作业强制全新克隆
script:
- git log --oneline > CHANGELOG.mdGIT_STRATEGY 同样可以在作业里覆盖项目设置,取值 clone、fetch 或 none(不获取代码,适合纯触发型作业)。
第三步,验证深度是否生效
在作业里直接看日志即可,Runner 执行的 git 命令会带 --depth 参数:
check-clone:
script:
- git log --oneline | wc -l # 输出条数应≈GIT_DEPTH
- git rev-parse --is-shallow-repository # true 表示浅仓库三个常见的坑
坑一,深度不够导致作业失败。 依赖历史的操作会踩到边界:合并请求的目标分支落后很多时,浅获取可能拿不到合并基线;用 git describe 生成版本号时,tag 超出了获取深度就会直接报错。解法不是全局调大,而是只给需要的作业调大 GIT_DEPTH。
坑二,需要推送的作业不要用浅克隆。 CI 里直接 git push 回仓库(比如自动生成 CHANGELOG 后回写)的作业,浅仓库推送会被 git 拒绝。这类作业应单独设置 GIT_DEPTH: 0。
坑三,深度不是越小越好。 设成 1 看似最快,但任何需要比较两个提交的步骤(diff 统计、增量测试选案)都会失败。20-50 是官方默认与新项目的常见取值,先从这个区间开始。
常见问题
问:GIT_DEPTH 设了 50,为什么有的作业拿到 100 条历史?
答:项目设置与作业变量是覆盖关系,作业里的 GIT_DEPTH 优先。另外 fetch 策略下本地已有更深的历史时不会主动截断,需要 clone 策略才会严格按深度执行。
问:减小深度会影响缓存命中吗?
答:两者互不影响。.git 目录本身不推荐作为缓存对象,依赖与构建产物才该走缓存;克隆深度只作用于代码获取阶段。
问:多项目流水线、子流水线要每处都配吗?
答:项目级设置对整个项目生效,子流水线复用同一项目的配置;跨项目触发的流水线以各自项目的设置为准,无需重复配置。
结语
克隆深度是个小配置,但它直接影响每条流水线的固定开销。先用项目设置把默认深度收紧,再给少数依赖历史的作业单独放开,是成本最低的优化路径。
想系统性地优化 CI 耗时?可以参考 CI 缓存配置实践 把依赖缓存一并配好,两条手段叠加效果更好。如果你在配置过程中遇到问题,欢迎在官网提交工单或预约一场 Demo,和我们的工程师直接聊聊你的流水线。

