CI 每个作业都在全量克隆,浅克隆与获取深度怎么配

极狐GitLab
2026年11月17日
24180
分享:

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.md

GIT_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,和我们的工程师直接聊聊你的流水线。