GitLab CI引用workflow模板引发分支流水线异常的解决方案咨询

问题根源梳理 #

1. include的workflow模板无效：GitLab CI的workflow: rules评估逻辑是先判断是否创建流水线，再解析include内容，因此通过include引入的workflow规则无法控制流水线的创建。
2. 分支不存在导致include失败：deploy.yml的引用使用ref: $CI_COMMIT_BRANCH，新建分支时模板项目无对应分支，直接触发include异常。
3. include加规则后模板缺失：非允许分支下include不执行，.staging模板未加载，但deploy-staging任务仍尝试继承该模板，导致配置解析报错。

可行解决方案 #

方案一：全局CI模板复用（需管理员权限）

利用GitLab实例级CI/CD模板功能，将workflow规则统一维护在全局模板中，所有项目自动继承：

1. 在GitLab实例后台创建全局CI模板，内容如下：

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_BRANCH == "staging"
    - when: never

2. 所有项目的.gitlab-ci.yml无需再写workflow规则，直接继承全局模板即可。

• 优势：完全实现规则复用，后续修改只需更新全局模板，维护成本为0；
• 劣势：需要GitLab管理员权限，无法单独排除个别项目。

方案二：主配置写死workflow+固定模板分支

如果没有管理员权限，可采用“主配置写极简workflow+固定模板分支”的方式：
修改项目的.gitlab-ci.yml：

# 直接在主配置中写workflow规则，确保优先生效
workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_BRANCH == "staging"
    - when: never

include:
  - project: "senagon.com/templates/ci/deploy-templates"
    file:
      - "workflow.yml"
  # 将ref改为固定分支（如main），避免分支不存在导致的include失败
  - project: "projects/deploy-templates"
    ref: main
    file:
      - "deploy.yml"

deploy-staging:
  stage: deploy
  extends:
    - .staging
  script:
    - echo "Test"

• 优势：彻底解决分支不存在的include异常，workflow规则直接生效；
• 劣势：若需修改允许分支，需批量更新项目配置（可通过脚本批量处理）。

方案三：全局变量统一管控（需管理员权限）

通过GitLab全局项目变量统一管理允许创建流水线的分支：

1. 管理员在GitLab实例中设置全局变量CI_ALLOWED_BRANCHES，值为main,staging；
2. 项目的.gitlab-ci.yml配置如下：

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH in $CI_ALLOWED_BRANCHES
    - when: never

include:
  - project: "senagon.com/templates/ci/deploy-templates"
    file:
      - "workflow.yml"
  - project: "projects/deploy-templates"
    ref: $CI_COMMIT_BRANCH
    file:
      - "deploy.yml"
    # 仅允许分支下才加载模板
    rules:
      - if: $CI_COMMIT_BRANCH in $CI_ALLOWED_BRANCHES

deploy-staging:
  stage: deploy
  extends:
    - .staging
  script:
    - echo "Test"
  # 仅允许分支下才执行任务
  rules:
    - if: $CI_COMMIT_BRANCH in $CI_ALLOWED_BRANCHES

• 优势：修改允许分支只需更新全局变量，无需调整项目配置；
• 劣势：需要管理员权限，手动触发非允许分支流水线仍会因模板缺失报错，但自动触发已被workflow阻止。

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