GitLab CI 进阶
本篇要点:拿到一条又慢又乱的 GitLab 流水线,你能判断该拆哪一层、该加什么条件、该在哪里并行,并把 Runner 侧的资源算清楚。 前置文章:《GitHub Actions 工程化实践》讲的是 GitHub Actions 的复用与权限模型,这一章换到 GitLab,重点在对齐概念差异,而不是从零再学一遍流水线。
一、为什么需要它
2026 年 5 月,一个 40 人的团队把主仓库从 GitHub 迁到自建 GitLab。迁完之后单仓变单库(monorepo),五个服务、一个前端、一个共享库全在一个仓库里,.gitlab-ci.yml 从 380 行长到 3100 行,因为每个服务都要单独定义构建、测试、打包、部署。
三条症状同时出现。
第一,改一行 README 也要跑 47 分钟。流水线没有 workflow:rules,任何 push 都触发全量;后面排队的 MR 平均等 40 分钟才轮上 Runner。
第二,五个服务的 node_modules 各装一遍,同一份依赖在六个 job 里重复下载了六次。有人提议加缓存,加完之后命中率还是 0,因为 cache:key 写的是固定字符串,而 GitLab 的缓存是「每个 Runner 本地一份」,任务被调度到别的 Runner 上就是空目录。
第三,测试和构建必须等 lint 全部跑完才开始,因为都写在 stages: 的顺序里。其实测试和 lint 之间没有任何依赖,纯粹是被阶段模型串起来的。
这三个问题分别对应 GitLab CI 的三组机制:workflow:rules 控制流水线生不生成,needs 把阶段串行改成任务图,cache 与 artifacts 分清「加速用的临时文件」和「必须传递的产出」。这一章按这个顺序拆。
二、核心概念
2.1 include 与 extends:拆文件,不拆语义
include 把外部 YAML 拼进来,来源有四种:local(同仓库相对路径)、remote(公开 URL,需带完整地址)、template(GitLab 自带模板,如 Jobs/SAST.gitlab-ci.yml)、project(另一个仓库的文件,要写 file 和 ref)。合并发生在流水线创建时,被引入的文件和主文件是同一份配置,不是运行时引用。
extends 做的是单个 job 的继承,规则跟 YAML 锚点不一样,值得单独记:
| 类型 | extends 的行为 | 举例 |
|---|---|---|
| 哈希(map) | 深合并,键逐个覆盖 | variables、cache、script 之外的配置块 |
| 数组(array) | 整体替换,不拼接 | script、only、tags |
| 字符串/布尔 | 覆盖 | image、allow_failure |
表 3-1 extends 的合并规则,第二行是「为什么我的 script 只剩最后一行」的答案
数组整体替换这条最容易被误解。子 job 写了 script:,父 job 的 script 会被完整丢掉,不会在前面接上。想复用片段得用 !reference 自定义标签,它引用的是某个键的内容,可以插进数组中间:
.default-script: &default-script
- echo "准备环境"
- npm ci
test:
script:
- !reference [.default-script, script]
- node --test另外 include:project 里的 ref 建议写 tag 而不是分支名,否则上游改一次分支,所有下游流水线的行为一起变,而且没人知道变了。
2.2 rules 与 workflow:一个管 job,一个管整条流水线
rules 写在 job 里,逐条匹配,命中第一条就停,用它的 when 决定这个 job 加不加入流水线。workflow:rules 写在顶层,决定整条流水线建不建立——所有规则都不匹配时,这次 push 什么都不会跑,页面上也不会留下一条空的流水线记录。
两者的语义差别很大,混用会出问题。比如「只有 MR 才跑测试」,写在 job 的 rules 里,结果是流水线照样创建、其它 job 照样跑;写在 workflow:rules 里,这次 push 就完全不产生流水线。
rules 的三个判断条件:
if:基于变量表达式,支持==、!=、=~、!~,可以用&&、||和括号组合。changes:文件路径是否变化。在「新建分支的第一次 push」场景下,GitLab 没有可比较的基线,changes会判定为真,这一点常导致「明明没改前端也跑了前端」。exists:某路径是否存在,用于判断仓库里有没有对应目录。
changes 的正确写法要配合 compare_to,或者干脆用 rules:changes:paths 加 when: never 做排除。还有一个必须记住的约束:rules 里不能用 and/or 关键字,只能用符号,也不能把 if 和 changes 用符号连起来——一个条件里只能有一个 if 加一个 changes,两者是「与」的关系。
2.3 needs:把阶段串行改成 DAG
默认行为是按 stages 顺序走,前一阶段全部成功才进下一阶段。needs 声明「我这个 job 只等这几个」,于是它可以在依赖满足时立刻开始,不等整个阶段收尾。这套模型叫有向无环图(directed acyclic graph,DAG)。
图 3-1 同一个仓库在阶段串行与 DAG 两种模型下的时间线差别
如图 3-1 所示,任务图的形状没变,变的是等待关系:build-web 不用等 test-api 跑完。在五个服务的仓库里,这一处改动通常能砍掉三分之一的总时长。
用 needs 有三个边界要记牢。其一,needs 引用的 job 必须存在于同一条流水线,跨项目要写 needs:project,它要求那个项目已经跑过一次成功流水线,且拿到的制品有有效期。其二,用了 needs 的 job 不再获得前序阶段制品的自动下载,需要显式写 needs: [job, artifact: true]。其三,needs 可以指向同一阶段的 job,这是让同一阶段内部也并行的办法。
2.4 cache 与 artifacts:两种东西,不能混
| 维度 | cache | artifacts |
|---|---|---|
| 用途 | 加速,如依赖目录 | 传递产出,如编译结果 |
| 存放位置 | Runner 本地目录或对象存储 | GitLab 服务器 |
| 是否保证存在 | 不保证,可能被清掉 | 保证,除非过期或被删 |
| 默认过期 | 无(按 cache:key 覆盖) | 30 天(expire_in) |
| 能不能跨 Runner | 配了分布式缓存才可以 | 可以 |
| 失败时是否上传 | 否 | 默认是,when: on_failure 可调 |
表 3-2 缓存与制品的分工,把编译产物放进 cache 是最常见的错配
cache:key:files 最多接受两个文件,GitLab 会对这两个文件的内容算哈希拼进 key。写成 cache:key:files: [package-lock.json],依赖一改 key 就变,不会读到旧依赖;再配 cache:key:prefix 区分服务,避免五个服务互相覆盖同一个 key。
分布式缓存要配 CACHE_S3_SERVER_ADDRESS 之类的环境变量,或者用 cache:type: s3。不配的话,缓存只在单个 Runner 上有意义,一旦开了伸缩,命中率就掉下来。
2.5 多项目与父子流水线
两种组织方式用途不同。trigger:project 是下游流水线,适合「A 服务改了,触发 B 服务重新集成测试」这种跨仓联动,加 strategy: depend 后上游会等下游结果。trigger:include 是子流水线,适合单仓多服务:父流水线只负责生成结构,每个服务的配置单独一个文件,rules:changes 只让改动的那个服务生成子流水线。
子流水线还能动态生成:前一个 job 用脚本产出 generated.yml 当作 artifacts,下一个 job 用 trigger:include:artifact 引用它。配置量大的仓库靠这个把「一份大文件」变成「一份模板加若干生成结果」。
2.6 Runner:执行器、标签与伸缩
Runner 是真正执行 job 的进程。三个配置项决定它的行为:
- 执行器(executor):
docker最常用,kubernetes适合已有集群,shell直接跑在宿主机上、速度快但没有隔离,docker-autoscaler是现在做弹性的主流选择。 - 标签(
tags):job 和 Runner 靠标签匹配,job 不写tags就会落到「允许运行未打标签任务」的 Runner 上,那通常是一台共享机器。 - 并发(
concurrent):config.toml里的总并发数,配合单个 Runner 的limit,决定这台机器同时能跑几个 job。
注册方式在 GitLab 16 之后换成了 runner authentication token,早期的 registration token 已不再使用;docker-machine 执行器的自动伸缩方案也已弃用,现在用 GitLab Runner Autoscaler 配 AWS Fleets 或 Google Cloud 插件,按队列长度伸缩实例。
三、动手实践
目标:把那条 47 分钟的流水线压到 12 分钟以内,检查项一个不删。先量基线,再逐项改。
3.1 第一步:workflow:rules 砍掉无效流水线
workflow:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_COMMIT_TAG
- if: $CI_PIPELINE_SOURCE == "web"
- when: never运行结果(同一周内的流水线数量对比):
改动前:一周 412 条流水线,其中 178 条由纯文档改动触发
改动后:一周 236 条流水线,纯文档 MR 被 paths 排除后再减 96 条
排队时间:中位数 40 分钟 → 6 分钟最后那行 when: never 不能省。workflow:rules 的规则是逐条匹配,全都不命中时流水线不会创建;但没有显式 never 时,行为依赖版本默认值,写清楚比依赖默认值可靠。另外注意 merge_request_event 与分支 push 同时命中会产生重复流水线,所以上面把默认分支单独列一条,而不是用 push 通配。
3.2 第二步:拆成 include 加 extends
主文件只留结构,公共部分进 .gitlab/ci/:
# .gitlab-ci.yml
include:
- local: .gitlab/ci/base.yml
- local: .gitlab/ci/test.yml
- local: .gitlab/ci/build.yml
stages: [verify, test, build, deploy]# .gitlab/ci/base.yml
.node:
image: node:22-alpine
cache:
key:
files: [package-lock.json]
prefix: $CI_JOB_NAME
paths: [.npm/]
policy: pull-push
before_script:
- npm config set cache .npm --global
- npm ci --prefer-offline --no-audit运行结果(gitlab-ci lint 本地校验通过后的 job 列表):
$ gitlab-ci-local --list
lint verify
test-api test
test-web test
build-api build
build-web build
deploy-staging deploy$CI_JOB_NAME 放进 cache:key:prefix 是为了让每个 job 有独立缓存,避免 test-api 和 test-web 同时写一个目录导致互相覆盖。.npm/ 是 npm 的缓存目录,把它缓存起来比缓存 node_modules 更稳——后者在跨平台或 Node 大版本切换时会带上不兼容的原生模块。
3.3 第三步:用 needs 建 DAG
test-api:
extends: .node
stage: test
needs: [lint]
rules:
- changes: [services/api/**/*]
script: [npm test --workspace services/api]
build-api:
extends: .node
stage: build
needs:
- job: test-api
artifacts: true
rules:
- changes: [services/api/**/*]
script:
- npm run build --workspace services/api
artifacts:
paths: [services/api/dist/]
expire_in: 3 days运行结果(流水线视图的耗时对比):
改动前(stage 串行):
verify 4m12s → test 21m38s → build 18m05s → deploy 3m20s 合计 47m15s
改动后(DAG + changes 过滤):
lint 1m50s
test-api 6m04s (needs: lint)
test-web 5m12s (needs: lint)
build-api 2m38s (needs: test-api)
build-web 1m46s (needs: test-web)
deploy 1m30s
关键路径 12m02s关键路径(critical path)是从流水线开始到结束的最长链,它才决定总时长。这里 lint → test-api → build-api → deploy 是 11 分 52 秒,比串行的 47 分钟少掉四分之三,靠的不是让 job 更快,而是让没有依赖关系的 job 不再互相等。
3.4 第四步:Runner 打标签并开伸缩
# /etc/gitlab-runner/config.toml
concurrent = 24
[[runners]]
name = "docker-autoscaler-aws"
url = "https://gitlab.example.com"
executor = "docker-autoscaler"
limit = 8
[runners.cache]
Type = "s3"
Shared = true
[runners.cache.s3]
ServerAddress = "s3.ap-northeast-1.amazonaws.com"
BucketName = "gitlab-runner-cache"
BucketLocation = "ap-northeast-1"运行结果(gitlab-runner list 与队列观察):
Runtime platform arch=amd64 os=linux pid=2214
docker-autoscaler-aws Url=https://gitlab.example.com Executor=docker-autoscaler
并发上限 24,单 Runner 上限 8,缓存走 S3 共享
高峰队列深度:改动前 37 → 改动后 2Shared = true 是关键一行。它让缓存写入 S3 而不是 Runner 本地磁盘,伸缩出来的新实例能直接读到旧实例写的缓存,否则每次扩容都是冷启动。
四、常见误解
很多人以为 extends 像编程里的继承,子类会拿到父类的全部内容再叠加。实际上数组是整体替换的,子 job 写了自己的 script,父 job 的 script 就没了。要拼接只能用 !reference,而且得写在数组元素的位置上。
很多人以为 needs 只是让流水线图好看。实际上它改变的是触发时机和制品传递方式:用了 needs 就不再自动下载前序阶段的全部制品,也不再有「前一阶段全绿才继续」的保护。写完 needs 必须确认每个 job 的输入都显式声明了。
很多人以为缓存加了就会快。GitLab 的缓存默认存在 Runner 本地,不配分布式缓存的情况下,任务一旦调度到别的 Runner 就是空的;再加上 cache:key 写死字符串,即使命中也可能读到过期的依赖树。缓存要同时满足「key 跟依赖清单绑定」和「存储跨 Runner 共享」两个条件才有意义。
五、小结
《GitHub Actions 工程化实践》的 GitHub Actions 靠「事件 + 复用 + 权限」三板斧,GitLab 这一侧换成「规则 + 图 + 执行器」:
workflow:rules管流水线建不建,rules管 job 加不加,两者层级不同,别写错地方。extends是深合并,但数组整体替换;跨片段复用用!reference。needs的核心收益是缩短关键路径,代价是失去阶段级的制品自动传递。cache用于加速且不保证存在,artifacts用于传递且保证存在。编译产物该进artifacts。- Runner 的标签要和 job 的
tags对齐,伸缩必须配共享缓存,否则扩容等于冷启动。
六、相关文章
《CICD 入门:从提交到上线的全链路》留了一个没深究的细节:npm ci 严格按 lockfile 安装,所以同一个 lockfile 装出来的依赖树是一样的。但换成 Python 的 pip、Go 的模块代理、或者带上 latest 标签的基础镜像,这条保证就断了——同一份代码在两个时间点构建出两个不同的镜像,预发验证过的镜像和生产上跑的不是同一份字节。相关文章就讲怎么把「可复现」变成能验证的性质:依赖怎么锁死、多阶段构建怎么把镜像从 1.2 GB 压到 90 MB、构建完之后用什么校验证明两次构建的产物一致。
继续阅读:[《构建可复现:依赖锁定与多阶段镜像》 构建可复现:依赖锁定与多阶段镜像](/guide/cicd/build-reproducibility.html)