1. 变量分层概述
什么是 GitLab CI 变量
GitLab CI 变量是流水线运行时注入到 Job 环境中的键值对（Key-Value Pair），用于控制构建行为、传递敏感信息、切换部署目标等。变量可在 .gitlab-ci.yml 中直接定义，也可通过 GitLab UI、API、Group/Project 设置、甚至外部文件注入。
核心作用：将配置与代码分离，使同一份流水线定义在不同环境（开发/测试/生产）下复用，同时避免硬编码密钥和路径。
为什么需要分层治理
在真实项目中，变量来源极其分散：
- 实例级变量：全局通用配置，如公司级镜像仓库地址。
- 组级变量：团队共享的数据库连接串、告警 Webhook。
- 项目级变量：当前仓库专属的部署密钥、环境标识。
- 流水线级变量：通过 API 或 UI 手动触发时传入的临时参数。
- Job 级变量：仅在某个 Job 内生效的局部覆盖。
若不分层管理，会出现以下问题：
| 问题 | 后果 |
|---|---|
| 变量散落在多个位置 | 排查困难，新人难以理解变量来源 |
| 同名变量互相覆盖 | 流水线行为不可预测，生产环境误用测试密钥 |
| 敏感信息无层级隔离 | 开发人员可能看到生产数据库密码 |
| 缺乏优先级规则 | 修改低层级变量无法生效，调试成本高 |
最佳实践：分层治理的核心是“高优先级覆盖低优先级”，让通用配置下沉到组/实例级，敏感或临时配置上浮到项目/流水线级，形成清晰的变量作用域边界。
变量优先级规则总览
GitLab 按照从低到高的顺序合并变量，高优先级变量会覆盖低优先级同名变量。完整优先级链如下：
- 最低优先级：
.gitlab-ci.yml中variables关键字定义的变量 - 组级变量（Group-level variables）
- 项目级变量（Project-level variables）
- 流水线级变量（Pipeline-level variables，通过 API/UI 手动触发传入）
- Job 级变量（Job-level
variables或before_script中定义） - 最高优先级：受保护变量（Protected variables）——仅在受保护分支或标签上运行且变量标记为 protected 时生效
下面用一张分层结构图直观展示变量来源与优先级流向：
变量覆盖示例
假设在 .gitlab-ci.yml 中定义了 DEPLOY_ENV: staging，同时在项目级变量中设置了 DEPLOY_ENV: production，则最终 Job 中 DEPLOY_ENV 的值为 production。若再通过 API 手动触发流水线时传入 DEPLOY_ENV=canary，则最终值为 canary。
# .gitlab-ci.yml 示例
variables:
DEPLOY_ENV: staging
APP_VERSION: "1.0.0"
deploy-job:
stage: deploy
variables:
DEPLOY_ENV: production # Job 级覆盖流水线级
script:
- echo "Deploying to $DEPLOY_ENV" # 输出 production
注意：受保护变量仅在满足以下两个条件时才会生效：① 变量在 UI 中勾选了“Protected”；② 当前流水线运行在受保护分支（如 main）或受保护标签上。非受保护分支即使有同名变量，也不会使用受保护变量的值。
分层治理的核心收益
| 收益 | 说明 |
|---|---|
| 可追溯性 | 每个变量都有明确的层级归属，排查问题时能快速定位来源 |
| 安全性 | 敏感变量（密码、）放在项目级并标记为受保护，避免低层级泄露 |
| 复用性 | 通用配置（镜像地址、超时时间）放在组级，所有子项目自动继承 |
| 灵活性 | 临时覆盖通过流水线级变量传入，无需修改代码或 UI 配置 |