📚 课程目录第3章组级变量

3. 组级变量：在 Group Settings 中配置、继承规则、组内项目共享策略

组级变量（Group-level Variables）是 GitLab CI 变量分层治理中的关键中间层。它位于实例级变量之下、项目级变量之上，为隶属于同一 Group 的所有项目提供统一的变量注入能力。通过组级变量，团队可以集中管理共享密钥、环境配置和通用参数，避免在每个项目中重复定义，同时保持对下层项目的可控覆盖。

3.1 组级变量的配置路径

组级变量的配置入口位于 Group 的 Settings 菜单中，操作路径如下：

登录 GitLab，进入目标 Group 的主页。
点击左侧导航栏的 Settings → CI/CD。
展开 Variables 区域，点击 Add variable。

配置界面与项目级变量类似，但多了一个关键选项：Environment scope（环境作用域）。组级变量默认对所有环境生效，但你可以将其限定到特定环境（如 production、staging），实现环境级别的变量隔离。

  关键配置字段：
  Key：变量名称，建议使用大写字母和下划线（如 GROUP_DEPLOY_KEY）。
Value：变量值，支持明文或 Masked（掩码）显示。
Type：Variable（普通变量）或 File（文件类型变量）。
Environment scope：*（所有环境）或指定环境名称。
Protect：仅对受保护分支或标签可用。
Masked：在 CI 日志中隐藏变量值。

3.2 继承规则：自上而下的变量传递

组级变量的继承遵循 自上而下、逐层覆盖 的规则。当 Group 包含子 Group 或项目时，变量传递路径如下：

父 Group → 子 Group：父 Group 的变量自动继承给所有子 Group，除非子 Group 定义了同名变量进行覆盖。
Group → 项目：Group 变量自动注入到该 Group 下的所有项目，项目可以定义同名变量覆盖 Group 变量。
多层嵌套：在多层 Group 嵌套场景中，最内层（子 Group）的变量优先级最高，外层变量作为默认值。

继承优先级（从高到低）：
项目级变量 > 子 Group 级变量 > 父 Group 级变量 > 实例级变量
同名变量时，优先级高的变量会完全覆盖优先级低的变量，不会合并。

以下表格总结了不同层级变量的继承行为：

变量定义层级	是否继承给子 Group	是否继承给项目	能否被下层覆盖
实例级变量	是	是	是
父 Group 级变量	是	是	是
子 Group 级变量	否（仅向下）	是	是
项目级变量	不适用	仅自身	不适用（最底层）

3.3 组内项目共享策略

组级变量的核心价值在于实现 组内项目共享。通过合理设计，你可以让多个项目共用同一套变量，减少重复配置并降低维护成本。常见的共享策略包括：

统一密钥管理：将数据库密码、API 、云服务密钥等敏感信息定义为组级变量，所有项目自动继承，避免密钥散落。
环境配置标准化：定义 DEPLOY_SERVER、REGISTRY_URL 等环境相关变量，确保组内项目使用统一的部署目标。
CI 流程通用参数：如 CI_IMAGE_TAG、BUILD_TIMEOUT 等，统一构建行为。

注意： 组级变量对所有子项目可见。如果某个项目需要不同的值，必须在项目级定义同名变量进行覆盖。不要将仅适用于单个项目的变量放在组级，以免造成意外覆盖或安全风险。

3.4 组级变量继承与覆盖流程（SVG）

下图展示了组级变量从父 Group 到子 Group 再到项目的继承与覆盖流程：

3.5 组级变量使用场景示例

以下是一个实际的多项目共享场景：假设你有一个 backend-services Group，包含 auth-service、payment-service 和 notification-service 三个项目。你可以在 Group 级定义以下变量：

# 组级变量（backend-services Group）
DB_HOST=db.internal.example.com
DB_PORT=5432
REDIS_URL=redis://redis.internal.example.com:6379
KAFKA_BOOTSTRAP_SERVERS=kafka1.internal:9092,kafka2.internal:9092
DEPLOY_USER=deploy-bot

三个项目自动继承这些变量，无需各自定义。如果 payment-service 需要使用不同的数据库主机，只需在项目级定义 DB_HOST 变量覆盖即可：

# 项目级变量（payment-service 项目）
DB_HOST=db-payment.internal.example.com  # 覆盖组级变量

最佳实践： 将通用、稳定的配置放在组级变量中，将项目特有的配置放在项目级变量中。定期审计组级变量，移除不再使用的变量，避免变量膨胀。

3.6 组级变量与 CI 作业的交互

在 .gitlab-ci.yml 中，组级变量与项目级变量一样，可以直接通过 $VARIABLE_NAME 引用。以下是一个使用组级变量的示例：

# .gitlab-ci.yml
stages:
  - build
  - deploy

build-job:
  stage: build
  script:
    - echo "Building with DB_HOST=$DB_HOST"
    - docker build --build-arg DB_HOST=$DB_HOST -t myapp .

deploy-job:
  stage: deploy
  script:
    - echo "Deploying to $DEPLOY_SERVER"
    - ssh $DEPLOY_USER@$DEPLOY_SERVER "docker-compose up -d"
  only:
    - main

在这个例子中，$DB_HOST 和 $DEPLOY_USER 来自组级变量，$DEPLOY_SERVER 可能来自项目级变量。CI 作业在运行时自动合并所有层级的变量，按优先级规则确定最终值。

3.7 组级变量管理注意事项

变量可见性：组级变量对 Group 内所有成员可见（值可能被 Masked），但不会暴露给 Group 外的用户。
环境作用域：合理使用 Environment scope 可以避免变量在不同环境间混淆，例如将 PROD_ 限定为 production 环境。
变量数量限制：GitLab 对每个 Group 的变量数量有限制（通常为 200 个），超出后需要清理或升级套餐。
审计与变更：组级变量的变更会影响所有子项目，建议在修改前通知相关团队，避免意外破坏。

安全提醒： 不要在组级变量中存储明文密码或敏感信息，务必启用 Masked 选项。如果变量值包含特殊字符（如 $、#），请使用单引号包裹或进行转义。