如何通过GitLab REST API运行可传.gitlab-ci.yml的动态阶段一次性流水线？

核心结论 #

GitLab原生API不支持直接在触发流水线时传递完整的.gitlab-ci.yml内容，但可以通过以下几种方式实现动态流水线（包括动态阶段）的需求，无需在项目中固定写死配置：

方案1：利用CI_CONFIG_PATH变量指向远程动态配置 #

触发流水线时，通过API传递CI_CONFIG_PATH变量，指向一个能动态生成.gitlab-ci.yml内容的服务接口，GitLab会自动拉取该接口返回的YAML作为流水线配置，解析其中的阶段和任务。

步骤：

• 确保你的配置服务能根据参数生成对应结构的CI配置（比如接收PIPELINE_TYPE参数，返回包含多阶段的YAML内容）。
• 通过API触发流水线并传递变量：

  curl --request POST "https://gitlab.example.com/api/v4/projects/<项目ID>/pipeline" \
    --header "PRIVATE-TOKEN: <你的访问令牌>" \
    --form "variables[CI_CONFIG_PATH]=http://192.168.1.111:8888/getDynamicCIConfig?type=multi-stage"
  

这种方式无需项目中存在.gitlab-ci.yml，完全依赖远程动态生成的配置。

方案2：动态创建临时分支上传配置 #

如果不想依赖外部服务，可以通过API先创建临时分支，上传动态生成的.gitlab-ci.yml，触发该分支的流水线后再删除分支：

步骤：

1. 生成包含动态阶段的.gitlab-ci.yml内容。
2. 创建临时分支：

   curl --request POST "https://gitlab.example.com/api/v4/projects/<项目ID>/repository/branches" \
     --header "PRIVATE-TOKEN: <你的访问令牌>" \
     --form "branch=temp-pipeline-$(date +%s)" \
     --form "ref=main"
   

3. 上传动态配置到临时分支：

   curl --request PUT "https://gitlab.example.com/api/v4/projects/<项目ID>/repository/files/.gitlab-ci.yml" \
     --header "PRIVATE-TOKEN: <你的访问令牌>" \
     --form "branch=temp-pipeline-$(date +%s)" \
     --form "content=$(cat dynamic-ci-config.yml)" \
     --form "commit_message=Add dynamic CI config"
   

4. 触发临时分支的流水线：

   curl --request POST "https://gitlab.example.com/api/v4/projects/<项目ID>/pipeline" \
     --header "PRIVATE-TOKEN: <你的访问令牌>" \
     --form "ref=temp-pipeline-$(date +%s)"
   

5. 流水线完成后可删除临时分支：

   curl --request DELETE "https://gitlab.example.com/api/v4/projects/<项目ID>/repository/branches/temp-pipeline-$(date +%s)" \
     --header "PRIVATE-TOKEN: <你的访问令牌>"
   

方案3：结合动态子流水线（适合保留极简基础配置的场景） #

如果项目中可以保留一个极简的基础.gitlab-ci.yml，可以通过动态子流水线实现多阶段展示：

基础配置（项目中仅需这个）：

stages:
  - generate_config

generate_config:
  stage: generate_config
  script:
    - curl http://192.168.1.111:8888/getDynamicCIConfig?type=$PIPELINE_TYPE > dynamic-config.yml
  artifacts:
    paths:
      - dynamic-config.yml

trigger_dynamic_pipeline:
  stage: generate_config
  trigger:
    include:
      - artifact: dynamic-config.yml
        job: generate_config
    strategy: depend

触发时通过API传递PIPELINE_TYPE变量，主流水线会先拉取动态配置，再触发包含所有动态阶段的子流水线，子流水线会完整展示你需要的多阶段任务。

当前方案的问题说明 #

你当前的方案中，流水线只显示一个阶段是因为GitLab在解析.gitlab-ci.yml时就确定了阶段数量，脚本中curl拉取的Shell命令只是在build阶段的任务内部执行，不会修改流水线的阶段结构。要实现动态阶段，必须让GitLab在解析配置时就能识别到所有阶段，以上方案均可解决该问题。

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