Skip to content

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 自定义标签,它引用的是某个键的内容,可以插进数组中间:

yaml
.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:两种东西,不能混 ​

维度cacheartifacts
用途加速,如依赖目录传递产出,如编译结果
存放位置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 砍掉无效流水线 ​

yaml
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

运行结果(同一周内的流水线数量对比):

text
改动前:一周 412 条流水线,其中 178 条由纯文档改动触发
改动后:一周 236 条流水线,纯文档 MR 被 paths 排除后再减 96 条
排队时间:中位数 40 分钟 → 6 分钟

最后那行 when: never 不能省。workflow:rules 的规则是逐条匹配,全都不命中时流水线不会创建;但没有显式 never 时,行为依赖版本默认值,写清楚比依赖默认值可靠。另外注意 merge_request_event 与分支 push 同时命中会产生重复流水线,所以上面把默认分支单独列一条,而不是用 push 通配。

3.2 第二步:拆成 include 加 extends ​

主文件只留结构,公共部分进 .gitlab/ci/:

yaml
# .gitlab-ci.yml
include:
  - local: .gitlab/ci/base.yml
  - local: .gitlab/ci/test.yml
  - local: .gitlab/ci/build.yml

stages: [verify, test, build, deploy]
yaml
# .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 列表):

text
$ 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 ​

yaml
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

运行结果(流水线视图的耗时对比):

text
改动前(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 打标签并开伸缩 ​

toml
# /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 与队列观察):

text
Runtime platform  arch=amd64 os=linux pid=2214
docker-autoscaler-aws   Url=https://gitlab.example.com   Executor=docker-autoscaler
并发上限 24,单 Runner 上限 8,缓存走 S3 共享
高峰队列深度:改动前 37 → 改动后 2

Shared = 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)