GitLab CI规则引用路径报错：paths应为字符串数组，求排查解决

问题场景 #

你尝试复用路径配置到GitLab CI规则中，配置如下：

.my-paths:
    paths:
        - path/to/file.1
        - path/to/file.2

.my-rule:
    rules:
        - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
          changes:
              compare_to: "refs/heads/main"
              paths:
                  - !reference [.my-paths, paths]
                  - path/to/file.3
                  - path/to/file.4

my-job:
    stage: build
    script:
        - 'echo "Do Something!"'
    rules:
        - !reference [.my-rule, rules]

运行时触发错误：jobs:my-job:rules:rule:changes paths should be an array of strings

错误原因 #

你在paths数组中用!reference引用了整个.my-paths的paths数组，导致最终paths变成嵌套数组（外层数组包含内层数组）。GitLab CI要求changes.paths必须是纯字符串数组，不允许嵌套结构，因此抛出报错。

注意：GitLab CI的!reference标签仅在script、before_script、after_script这类字段中会自动展开引用的数组，在changes.paths等其他数组字段中不会做展开处理，直接将引用的数组作为单个元素放入外层数组，造成嵌套。

解决方法 #

方法1：使用YAML锚点定义单路径复用 #

通过YAML锚点逐个定义可复用的路径，避免数组嵌套：

# 定义单个路径的锚点
&path1 path/to/file.1
&path2 path/to/file.2

.my-rule:
    rules:
        - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
          changes:
              compare_to: "refs/heads/main"
              paths:
                  - *path1
                  - *path2
                  - path/to/file.3
                  - path/to/file.4

my-job:
    stage: build
    script:
        - 'echo "Do Something!"'
    rules:
        - !reference [.my-rule, rules]

方法2：定义包含完整路径的复用块 #

如果需要复用的路径组合固定，直接定义包含所有路径的复用块，直接引用整个paths：

.my-full-paths:
    paths:
        - path/to/file.1
        - path/to/file.2
        - path/to/file.3
        - path/to/file.4

.my-rule:
    rules:
        - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
          changes:
              compare_to: "refs/heads/main"
              paths: !reference [.my-full-paths, paths]

my-job:
    stage: build
    script:
        - 'echo "Do Something!"'
    rules:
        - !reference [.my-rule, rules]

方法3：升级GitLab版本（若可行） #

GitLab后续版本优化了!reference在数组字段中的展开逻辑，升级到最新版本后，可能支持直接在paths数组中嵌套!reference而不产生嵌套数组。

参考文档翻译（原文档内容） #

在script、before_script和after_script中嵌套引用标签
你可以在script、before_script和after_script数组中嵌套!reference标签，将复用的脚本片段插入到数组中。例如：

.build-script:
  script:
    - echo "开始构建"
    - npm install

.test-script:
  script:
    - echo "开始测试"
    - npm test

job:
  script:
    - !reference [.build-script, script]
    - !reference [.test-script, script]
    - echo "部署"

此配置会将.build-script和.test-script中的脚本合并到job的script数组中，最终执行顺序为：构建脚本 → 测试脚本 → 部署命令。

内容的提问来源于stack exchange，提问作者urbanSoft