GitLab CI/CD下游流水线SF_ENV变量传递失败及分支配置疑问

问题描述 #

我开发了一个GitLab CI/CD流水线，在调用下游流水线时，DOCKER_IMAGE变量可正常传递生效，但SF_ENV变量无法正常传递，GitLab报错：

Unable to run pipeline

• ci/sf-deploy.gitlab-ci.yml: SF_ENV input: $SF_ENV cannot be used because it is not in the list of allowed options

相关配置文件 #

.gitlab-ci.yml

default:
  tags:
    - aws-docker

stages:
  - validate
  - default-pipeline

variables:
  SF_ENV: "dev"
  DEV_BRANCH: "develop"
  QUAL_BRANCH: "release/1.48"
  VALIDATION_BRANCH: "release/1.47"
  DOCKER_IMAGE: "sfdx-20260423"

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH =~ /(master|develop|release\/)/'
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME =~ /(master|develop|release\/)/'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "$DEV_BRANCH" || $CI_COMMIT_BRANCH == "$DEV_BRANCH"'
  variables:
    SF_ENV: "dev"
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "$QUAL_BRANCH" || $CI_COMMIT_BRANCH == "$QUAL_BRANCH"'
  variables:
    SF_ENV: "qual"
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "$VALIDATION_BRANCH" || $CI_COMMIT_BRANCH == "$VALIDATION_BRANCH"'
  variables:
    SF_ENV: "validation"
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master" || $CI_COMMIT_BRANCH == "master"'
  variables:
    SF_ENV: "staging"

# Validate a Pull Request
validate-merge-request:
  stage: validate
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME =~ /(master|develop|release\/)/'
      when: on_success
    - when: never
  trigger:
    include:
      - local: "ci/sf-deploy.gitlab-ci.yml"
        inputs:
          DOCKER_IMAGE: "$DOCKER_IMAGE"
          SF_ENV: "$SF_ENV"

default-pipeline:
  needs: []
  rules:
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME =~ /(master|develop|release\/)/'
      when: on_success
    - when: never
  stage: default-pipeline
  script:
    - echo "$SF_ENV";

ci/sf-deploy.gitlab-ci.yml

spec:
  inputs:
    SF_ENV:
      description: "The SF environment to target"
      options: ["dev", "qual", "staging", "validation", "production"]
    DOCKER_IMAGE:
      description: "The docker image name to use from JFrog"
      type: string
    JOB_NAME:
      description: "Job to perform"
      options: ["validate", "deploy"]
      default: "validate"
---
stages:
  - validate-merge-request

.base-deploy:
  image: **************/sf-ci:$[[ inputs.DOCKER_IMAGE ]]

validate-$[[ inputs.SF_ENV ]]:
  extends: .base-deploy
  rules:
    - if: '"$[[ inputs.JOB_NAME ]]" == "validate"'
      when: on_success
    - when: never
  stage: validate-merge-request
  environment:
    name: $[[ inputs.SF_ENV ]]
  script:
    - echo "$SF_ENV";

疑问 #

1. 为何DOCKER_IMAGE可正常传递，SF_ENV却失败？
2. 通过workflow根据目标分支设置SF_ENV的方式是否正确？

解答 #

1. 变量传递差异的原因 #

• 下游输入校验规则不同：下游流水线中DOCKER_IMAGE的类型是string，无选项限制，GitLab会直接接受上游传递的变量引用；而SF_ENV定义了options列表，GitLab会在流水线初始化阶段校验传入值是否在允许范围内。
• 上游变量未被正确解析：你的workflow配置存在语法错误，后续针对QUAL_BRANCH、VALIDATION_BRANCH、master的分支规则没有被包含在workflow.rules数组内，导致这些规则从未执行，SF_ENV可能始终使用全局默认值，甚至在触发下游时，变量引用$SF_ENV被当作字符串字面量传递，而该值不在options列表中，最终触发报错。

2. workflow设置SF_ENV的方式修正 #

通过workflow根据分支设置变量的方式是可行的，但你的配置存在语法错误，正确的写法需要将所有分支规则嵌套在workflow.rules数组内：

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH =~ /(master|develop|release\/)/'
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME =~ /(master|develop|release\/)/'
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "$DEV_BRANCH" || $CI_COMMIT_BRANCH == "$DEV_BRANCH"'
      variables:
        SF_ENV: "dev"
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "$QUAL_BRANCH" || $CI_COMMIT_BRANCH == "$QUAL_BRANCH"'
      variables:
        SF_ENV: "qual"
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "$VALIDATION_BRANCH" || $CI_COMMIT_BRANCH == "$VALIDATION_BRANCH"'
      variables:
        SF_ENV: "validation"
    - if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master" || $CI_COMMIT_BRANCH == "master"'
      variables:
        SF_ENV: "staging"

同时，为确保下游能正确接收变量值，建议在trigger的inputs中使用GitLab模板表达式显式解析变量：

trigger:
  include:
    - local: "ci/sf-deploy.gitlab-ci.yml"
      inputs:
        DOCKER_IMAGE: "$DOCKER_IMAGE"
        SF_ENV: "$[[ SF_ENV ]]"

这样GitLab会在触发下游流水线前先解析出SF_ENV的实际值，确保符合下游的options校验要求。

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