Gitlab 如何实现变量管理

在 GitLab 中，变量管理是 CI/CD 流程的核心功能之一，用于安全地存储和传递配置参数、密钥或环境信息。以下是 GitLab 变量管理的 7 种实现方式 和最佳实践：

一、变量定义层级

GitLab 变量支持 四级作用域，优先级从高到低：

1. Job 变量（在 .gitlab-ci.yml 的 Job 内定义）
2. Project 变量（项目设置中定义）
3. Group 变量（群组设置中定义）
4. Instance 变量（管理员全局设置）

二、变量设置方法

1. 项目级变量（UI设置）

• 路径：项目 → Settings → CI/CD → Variables → Add variable
• 关键选项： Protect variable：仅保护分支可访问Mask variable：隐藏日志输出（敏感信息）Environment scope：指定生效环境（如 production）

2. YAML 内直接定义

variables:
  APP_NAME: "my-app"  # 全局变量

build:
  variables:
    BUILD_ARCH: "amd64"  # Job级变量
  script:
    - echo "Building $APP_NAME for $BUILD_ARCH"

3. Group/Instance 变量

• Group 变量：群组 → Settings → CI/CD → Variables
• Instance 变量：管理员 → Admin Area → CI/CD → Variables

三、动态变量生成

1. 通过 dotenv 跨 Job 传递

generate_vars:
  stage: setup
  script:
    - echo "DYNAMIC_DATE=$(date +%F)" > env.file
  artifacts:
    reports:
      dotenv: env.file  # 自动加载为变量

use_vars:
  stage: deploy
  script:
    - echo "Date is $DYNAMIC_DATE"  # 读取动态变量

2. 脚本生成变量

job:
  script:
    - export CUSTOM_VAR=$(curl -s https://example.com/api/version)
    - echo "$CUSTOM_VAR"  # 仅当前Shell生效

四、敏感变量保护

1. 隐藏变量值（Masking）

• 在 UI 添加变量时勾选 Mask variable
• 要求：变量值需符合正则 [a-zA-Z0-9+=/@:.~]{8,}

2. 限制变量作用域

deploy_prod:
  variables:
    AWS_KEY: $PROD_AWS_KEY  # 引用受保护的变量
  rules:
    - if: $CI_COMMIT_BRANCH == "main"  # 仅main分支可访问

五、变量使用技巧

1. 条件变量赋值

variables:
  DEPLOY_ENV: $CI_COMMIT_REF_NAME == "main" ? "prod" : "staging"

2. 嵌套变量引用

variables:
  BASE_DIR: "/builds"
  ARTIFACT_PATH: "$BASE_DIR/output"  # → /builds/output

3. 多行变量

variables:
  MULTILINE_SCRIPT: |
    echo "Line 1"
    echo "Line 2"
    
job:
  script:
    - eval "$MULTILINE_SCRIPT"

六、预定义变量（Built-in）

GitLab 提供 数百个预定义变量，常用示例：

script:
  - echo "Project ID: $CI_PROJECT_ID"
  - echo "Commit SHA: $CI_COMMIT_SHA"
  - echo "User Email: $GITLAB_USER_EMAIL"

七、调试与验证

1. 查看所有变量

debug:
  script:
    - printenv | sort  # 打印所有环境变量

2. 本地测试

# 使用 gitlab-runner 本地测试
gitlab-runner exec docker job-name --env VARIABLE_NAME="value"

3. 变量优先级检查

GitLab 遵循优先级规则：

Job变量 > Project变量 > Group变量 > Instance变量 > 预定义变量

八、最佳实践

1. 敏感信息：永远不要硬编码在 YAML 中，使用 UI 设置的 Masked+Protected 变量
2. 命名规范：统一使用 UPPER_SNAKE_CASE（如 DB_PASSWORD）
3. 环境隔离：通过 environment 关键字限制变量作用域
4. 文档化：在项目 Wiki 记录变量用途和依赖关系

完整示例

stages:
  - build
  - deploy

variables:
  APP_NAME: "my-app"  # 全局变量

build:
  stage: build
  script:
    - echo "Building $APP_NAME v$CI_PIPELINE_IID"
    - tar czf app-$CI_COMMIT_SHORT_SHA.tar.gz dist/  # 使用预定义变量
  artifacts:
    paths:
      - app-*.tar.gz

deploy_prod:
  stage: deploy
  variables:
    DEPLOY_KEY: $PROD_SSH_KEY  # 引用UI设置的敏感变量
  script:
    - scp -i "$DEPLOY_KEY" app-*.tar.gz user@prod-server:/deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

通过以上方法，可以实现安全、灵活的变量管理，适应从简单到复杂的所有 CI/CD 场景。