2、GitLab CI模板目录结构基础

目录结构是模板权限边界的第一道防线。在GitLab CI中，模板的存放位置决定了谁能读取、谁能引用、谁能覆盖。理解默认路径、自定义配置和层级规范，是后续进行权限评审的前提。

2.1 默认模板目录位置

GitLab官方将内置CI模板统一存放在安装目录下的固定路径：

/opt/gitlab/embedded/service/gitlab-rails/lib/gitlab/ci/templates/

该目录包含所有官方维护的模板文件（如 Auto-DevOps.gitlab-ci.yml、Security/SAST.gitlab-ci.yml 等），由GitLab版本发布时打包，普通用户无权修改。下表列出该目录的核心特征：

2.2 自定义模板目录配置

企业通常需要维护私有模板库。GitLab支持通过项目级设置或实例级配置来定义自定义模板目录。常见方式有两种：

• 项目内模板目录：在项目仓库根目录下创建 .gitlab/ci/templates/ 文件夹，该目录下的 .gitlab-ci.yml 文件可通过相对路径 include:local 引用。
• 实例级自定义模板目录：通过 gitlab.rb 配置文件中的 gitlab_ci['custom_template_dirs'] 参数指定一个或多个额外目录。

# /etc/gitlab/gitlab.rb 配置示例
gitlab_ci['custom_template_dirs'] = [
  "/var/opt/gitlab/custom-ci-templates",
  "/data/shared/security-templates"
]

配置生效后，这些目录下的模板文件可通过 include:template 以 Custom/ 前缀引用。下表对比两种自定义方式的差异：

2.3 目录层级规范

GitLab CI模板目录遵循一套清晰的层级约定，用于组织不同类别的模板。官方模板的层级结构如下：

templates/
├── Auto-DevOps.gitlab-ci.yml
├── Jobs/
│   ├── Build.gitlab-ci.yml
│   ├── Test.gitlab-ci.yml
│   └── Deploy.gitlab-ci.yml
├── Security/
│   ├── SAST.gitlab-ci.yml
│   ├── Secret-Detection.gitlab-ci.yml
│   └── DAST.gitlab-ci.yml
├── Verify/
│   ├── Browser-Performance.gitlab-ci.yml
│   └── Code-Quality.gitlab-ci.yml
└── Workflows/
    ├── Merge-Request.gitlab-ci.yml
    └── Branch-Pipelines.gitlab-ci.yml

层级规范的核心原则包括：

• 一级目录：按功能领域命名（如 Security/、Jobs/），首字母大写，使用单数形式。
• 模板文件：使用帕斯卡命名法（PascalCase），以 .gitlab-ci.yml 为后缀。
• 禁止嵌套过深：官方规范限制最多两级子目录，避免引用路径过长导致维护困难。
• 索引文件：每个目录下可包含 index.md 描述该分类的模板清单和使用说明。

2.4 目录结构与权限的关联

目录层级直接影响模板的引用路径和权限继承关系。在权限评审中，需要关注以下映射：

• 路径即身份：模板的引用路径（如 Security/SAST.gitlab-ci.yml）决定了它在权限模型中的“身份标识”。
• 目录权限继承：文件系统层面，子目录默认继承父目录的权限。如果自定义模板目录的父目录权限过宽，所有子模板都会暴露。
• 覆盖优先级：当默认目录和自定义目录中存在同名模板时，自定义目录中的版本会覆盖默认版本。评审时需确认是否存在非预期的覆盖。