GitLab CI/CD外部YAML定义自定义阶段为何报错不存在？

问题场景 #

主配置文件 .gitlab-ci.yml 内容：

include:
- local: 'ci/jobs.yml'

stages:
- build
- deploy

build_job:
    stage: build
    script: echo "Building the project..."

被引入的 ci/jobs.yml 内容：

stages:
- pre-build

pre_job:
  stage: pre-build
  script:
    - echo "Running some pre build stuff..."

运行流水线时触发报错：

Unable to create pipeline
pre_job job: chosen stage pre-build does not exist; available stages are .pre, build, deploy, .post

直接把pre_job移到主配置、移除include后，流水线能正常运行。

原因分析 #

GitLab CI的stages合并规则是：只有主配置文件（.gitlab-ci.yml）中定义的stages会作为全局阶段列表生效，被引入的其他配置文件里的stages定义会被完全忽略。

你在ci/jobs.yml里定义的pre-build阶段根本没被合并到全局阶段列表中，所以流水线找不到这个阶段，自然报错。

解决方法 #

有两种可行的修复方式：

方式一：在主配置中添加缺失的阶段 #

修改.gitlab-ci.yml的stages，把pre-build加进去：

stages:
- pre-build
- build
- deploy

这样全局阶段列表就包含了pre-build，引入的pre_job就能正常关联到对应阶段。

方式二：统一在主配置管理stages #

删除ci/jobs.yml中的stages定义，只保留job内容：

pre_job:
  stage: pre-build
  script:
    - echo "Running some pre build stuff..."

同时确保主配置的stages里已经包含pre-build（同方式一的修改），这样所有阶段都由主配置统一管控，避免冲突。

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