zhaoweiguo 的知识库

GitLab CI/CD 变量体系

4分钟阅读

变量体系

变量来源与优先级

同名变量高优先级覆盖低优先级（高 → 低）：

  1. Trigger 触发时传入的变量（API / trigger job 传递）
  2. Project 级变量（Settings → CI/CD → Variables）
  3. Group / Subgroup 级变量
  4. Instance 级变量（管理员设置）
  5. .gitlab-ci.yml 中 variables 定义（Job 级 > 全局级）
  6. 预定义变量（Predefined）

另：带 environment scope 精确匹配的变量，优先于 scope 为 * 的同名变量。

常用预定义变量

变量说明
CI_COMMIT_SHA / CI_COMMIT_SHORT_SHA完整/短 commit hash
CI_COMMIT_BRANCH / CI_COMMIT_TAG / CI_COMMIT_REF_NAME分支名 / tag 名 / 二者之一
CI_COMMIT_REF_SLUG分支名的 URL 安全形式，常用作 cache key
CI_COMMIT_MESSAGE提交信息
CI_PIPELINE_ID / CI_PIPELINE_IID实例级 / 项目内流水线 ID
CI_PIPELINE_SOURCE触发来源（push/schedule/web/api/…）
CI_PIPELINE_URL流水线页面地址
CI_JOB_ID / CI_JOB_NAME / CI_JOB_STAGEJob 元信息
CI_JOB_TOKEN当前 Job 的临时 token（拉依赖、读写 registry）
CI_PROJECT_DIR代码检出目录
CI_PROJECT_PATH / CI_PROJECT_NAMEgroup/name / 项目名
CI_DEFAULT_BRANCH默认分支
CI_REGISTRY / CI_REGISTRY_IMAGERegistry 地址 / 本项目镜像路径
CI_REGISTRY_USER / CI_REGISTRY_PASSWORD登录 registry 的临时凭据
CI_MERGE_REQUEST_IIDMR 编号（仅 MR pipeline 有值）
CI_MERGE_REQUEST_SOURCE_BRANCH_NAMEMR 源分支
CI_MERGE_REQUEST_TARGET_BRANCH_NAMEMR 目标分支
CI_ENVIRONMENT_NAME / CI_ENVIRONMENT_URLenvironment 名 / URL
GITLAB_USER_LOGIN / GITLAB_USER_EMAIL触发者账号
CI_API_V4_URLAPI 地址，配合 token 调 REST API
CI_DEBUG_TRACE设 true 打印变量展开过程（⚠️ 会泄露敏感值，调试后移除）

完整列表以官方 predefined variables 文档为准，各 GitLab 版本略有差异。

自定义变量

Settings → CI/CD → Variables → Add variable：

选项说明
Key / Value变量名与值
Type: Variable / FileFile 类型把值写入临时文件，变量本身是文件路径
Protect variable仅 protected 分支/tag 的 Job 可用
Mask variable日志中显示为 [MASKED]；值需 ≥8 字符且仅含 Base64 合法字符集
Expand variable reference允许值中引用其他变量（$OTHER）
Environment scope限定生效环境（如仅 production），* 表示全部

yml 中定义：

variables:
  APP_ENV: staging
  DB_PASSWORD:
    value: ""               # 留空则运行时手动输入（manual job 场景）
    description: "数据库密码"
  RAW_CONFIG:
    value: '$BASE_CONFIG'
    expand: false           # 禁止展开，保留字面量

Job 级 variables 覆盖全局定义。

高频陷阱

  1. Protected 变量取不到：非 protected 分支上值为空。MR pipeline 按目标分支是否 protected 判断。解法：把分支设为 protected，或变量不勾 Protect（改用 Mask + 最小权限凭据）。
  2. Mask 失败：值含换行、特殊字符或太短时，勾选 Mask 会保存失败或日志仍明文。常见做法是 Base64 编码后存入、脚本里解码。
  3. File 类型用法：$KUBECONFIG_FILE 是路径不是内容，要 cat $KUBECONFIG_FILE 或 cp $KUBECONFIG_FILE ~/.kube/config。
  4. 密钥泄露：set -x、env、echo $VAR、CI_DEBUG_TRACE 都会把变量打进日志；masked 只掩盖变量原值，拼接/转码后的输出不保证被掩盖。

安全进阶

  • OIDC / ID tokens：id_tokens 关键字换取 JWT，向 AWS/GCP/Azure/Vault 换临时凭据，免维护长期密钥：
deploy:
  id_tokens:
    AWS_ID_TOKEN:
      aud: https://gitlab.example.com
  script:
    - aws sts assume-role-with-web-identity --role-arn $ROLE_ARN --web-identity-token $AWS_ID_TOKEN ...
  • External Secrets：secrets: 关键字对接 HashiCorp Vault 等，密钥不进 yml、不进 UI 配置。
  • 最小权限原则：CI_JOB_TOKEN 的可用范围可在 Settings → CI/CD → Job token permissions 收紧。

相关

关系图谱

反向链接