GitLab CI合并请求流水线预定义变量不可用问题求助

核心原因 #

报错rules:changes:compare_to is not a valid ref的本质是：GitLab在解析CI配置时，会提前校验compare_to的取值有效性——哪怕你加了if条件限制仅在MR事件中生效，非MR流水线场景下$CI_MERGE_REQUEST_TARGET_BRANCH_NAME变量为空，导致compare_to被解析成空字符串，触发无效引用的错误。

你提到同类作业能正常运行，大概率是那个作业的compare_to配置在非MR场景下没有触发校验（比如路径匹配逻辑不同，或者GitLab的规则解析优先级差异），但你的作业刚好触发了这个校验逻辑。

可行解决方案 #

方案1：移除多余的compare_to配置 #

在合并请求事件中，rules:changes默认就是和目标分支（$CI_MERGE_REQUEST_TARGET_BRANCH_NAME）对比变更文件，完全不需要额外指定compare_to。修改后的配置如下：

test-job:
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - folder/*
          - folder/important_subfolder/**/*
  needs: []
  image:
    name: alpine/latest
    entrypoint: [""]
  before_script:
    - cd folder
  script:
    - echo ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}

方案2：使用完整分支引用变量 #

如果确实需要显式指定compare_to，改用$CI_MERGE_REQUEST_TARGET_BRANCH_REF_NAME变量——这个变量存储的是完整的Git引用格式（比如refs/heads/main），而非单纯的分支名，能被GitLab正确识别为有效引用：

test-job:
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - folder/*
          - folder/important_subfolder/**/*
        compare_to: $CI_MERGE_REQUEST_TARGET_BRANCH_REF_NAME
  needs: []
  image:
    name: alpine/latest
    entrypoint: [""]
  before_script:
    - cd folder
  script:
    - echo ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}

方案3：用单引号包裹变量强制延迟替换 #

给变量加上单引号，让GitLab在执行阶段才替换变量，而非解析配置时就校验：

test-job:
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - folder/*
          - folder/important_subfolder/**/*
        compare_to: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME'
  needs: []
  image:
    name: alpine/latest
    entrypoint: [""]
  before_script:
    - cd folder
  script:
    - echo ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}

验证建议 #

优先尝试方案1，因为这是GitLab MR流水线的默认行为，最简洁且不易出错。如果必须保留compare_to，再尝试方案2或3。

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