GitLab CI 环境变量整理
分为两大类：内置预定义变量（系统自带） 、自定义变量（自己定义）；同时附带变量优先级、掩码/保护规则、调试方式。
查看所有变量：在 job 脚本里加
env或者printenv打印
一、通用基础变量（所有job都有）
| 变量 | 说明 |
|---|---|
CI |
流水线中固定为 true，用来判断当前是否在CI环境 |
CI_CONFIG_PATH |
ci配置文件路径，默认 .gitlab-ci.yml |
CI_DEBUG_TRACE |
开启调试日志，值为 true 时脚本会打印每一条命令 |
CI_SERVER_URL |
GitLab 访问地址（http://xxx） |
CI_SERVER_HOST |
GitLab 主机域名/IP |
CI_SERVER_PORT |
端口 |
CI_SERVER_PROTOCOL |
http / https |
CI_API_V4_URL |
GitLab v4 API地址 |
CI_API_GRAPHQL_URL |
GraphQL API地址 |
二、项目 & 仓库信息
| 变量 | 说明 |
|---|---|
CI_PROJECT_ID |
项目数字ID |
CI_PROJECT_NAME |
项目名称 |
CI_PROJECT_PATH |
项目路径（group/project） |
CI_PROJECT_PATH_SLUG |
转义后的路径，适合做域名、镜像tag |
CI_PROJECT_URL |
项目网页地址 |
CI_PROJECT_NAMESPACE |
命名空间（组名） |
CI_NAMESPACE_ID |
命名空间ID |
CI_REPOSITORY_URL |
git仓库地址（带CI token） |
三、提交/分支/标签相关
| 变量 | 说明 |
|---|---|
CI_COMMIT_SHA |
当前完整commit hash |
CI_COMMIT_SHORT_SHA |
前8位短hash，打镜像标签高频使用 |
CI_COMMIT_BRANCH |
分支名；MR流水线、tag流水线为空 |
CI_COMMIT_REF_NAME |
分支名 / tag名（通用，分支、tag都有） |
CI_COMMIT_REF_SLUG |
小写+特殊字符转 -，适合域名、资源名 |
CI_COMMIT_REF_PROTECTED |
是否是保护分支/保护tag：true/false |
CI_COMMIT_TAG |
仅tag流水线存在，tag名称；分支流水线为空 |
CI_COMMIT_TAG_MESSAGE |
tag注释信息 |
CI_COMMIT_BEFORE_SHA |
上一次commit；首次提交/MR流水线为全0 |
CI_COMMIT_MESSAGE |
完整commit信息 |
CI_COMMIT_TITLE |
commit第一行标题 |
CI_COMMIT_DESCRIPTION |
commit描述（去掉标题） |
CI_COMMIT_TIMESTAMP |
提交时间 ISO8601 UTC |
CI_COMMIT_AUTHOR |
作者 Name <email> |
四、流水线 Pipeline 变量
| 变量 | 说明 |
|---|---|
CI_PIPELINE_ID |
流水线ID |
CI_PIPELINE_IID |
项目内流水线序号（自增） |
CI_PIPELINE_URL |
流水线页面链接 |
CI_PIPELINE_SOURCE |
流水线触发源：push/merge_request_event/schedule/web/trigger/api |
CI_PIPELINE_TRIGGERED |
是否由trigger触发 |
CI_PIPELINE_CREATED_AT |
流水线创建时间 |
五、Job / 任务本身变量
| 变量 | 说明 |
|---|---|
CI_JOB_ID |
job全局ID |
CI_JOB_IID |
项目内job序号 |
CI_JOB_NAME |
yml里job的名称 |
CI_JOB_STAGE |
当前job所属stage名称 |
CI_JOB_URL |
job详情页链接 |
CI_JOB_STATUS |
状态（running/success/failed等） |
CI_JOB_TOKEN |
非常重要！Job Token，用于拉取依赖、访问包仓库、调用API |
CI_BUILDS_DIR |
runner构建根目录 |
CI_PROJECT_DIR |
代码拉取到本地的目录（工作目录） |
CI_RUNNER_ID |
当前执行runner id |
CI_RUNNER_TAGS |
runner标签 |
CI_DISPOSABLE_ENVIRONMENT |
docker/k8s执行器为true；shell/ssh执行器false |
六、Merge Request 合并请求（仅MR流水线才有）
| 变量 | 说明 |
|---|---|
CI_MERGE_REQUEST_IID |
MR序号 |
CI_MERGE_REQUEST_ID |
MR全局ID |
CI_MERGE_REQUEST_URL |
MR页面链接 |
CI_MERGE_REQUEST_TITLE |
MR标题 |
CI_MERGE_REQUEST_SOURCE_BRANCH_NAME |
MR源分支 |
CI_MERGE_REQUEST_TARGET_BRANCH_NAME |
MR目标分支 |
CI_MERGE_REQUEST_SOURCE_PROJECT_PATH |
源项目路径（跨项目MR） |
CI_MERGE_REQUEST_TARGET_PROJECT_PATH |
目标项目路径 |
七、Environment 环境部署变量（配置 environment:name 才生效）
| 变量 | 说明 |
|---|---|
CI_ENVIRONMENT_NAME |
环境名称，如 prod / test |
CI_ENVIRONMENT_SLUG |
转义后的环境名 |
CI_ENVIRONMENT_URL |
环境访问地址 |
CI_ENVIRONMENT_ID |
环境ID |
CI_DEPLOY_USER |
项目部署token用户名 |
CI_DEPLOY_PASSWORD |
项目部署token密码 |
八、依赖代理、制品库相关
| 变量 | 说明 |
|---|---|
CI_DEPENDENCY_PROXY_SERVER |
依赖代理地址 |
CI_DEPENDENCY_PROXY_USER / CI_DEPENDENCY_PROXY_PASSWORD |
依赖代理登录账号密码 |
九、自定义变量
定义位置（优先级从低 → 高，后面覆盖前面）
- 实例级（管理员后台）
- Group 组级别变量（组下所有项目继承）
- Project 项目级别变量（项目设置 → CI/CD → Variables）
.gitlab-ci.yml顶层variables:全局变量.gitlab-ci.ymljob内variables:单个job变量- 手动触发流水线时，页面上填入的变量（最高）
变量两个重要属性
- Protected（保护变量） ：仅保护分支/保护tag 流水线才能拿到；普通分支、MR流水线拿不到，适合生产密钥
- Masked（掩码变量） ：日志里自动替换成
[MASKED]，不能完全防止泄露，仅避免明文打印；要求：单行、≥8字符、不能含空格 - 还有
File类型变量：变量值写入临时文件，变量值为文件路径，适合SSH私钥、证书
注意：yml里写死的变量不适合放密钥，会提交到仓库，优先放UI变量
十、常用示例
build:
stage: build
variables:
IMAGE_TAG: $CI_COMMIT_SHORT_SHA
script:
- docker build -t $CI_REGISTRY_IMAGE:$IMAGE_TAG .十一、补充坑点
CI_COMMIT_BRANCH在MR流水线是空！判断分支优先用CI_COMMIT_REF_NAME+CI_PIPELINE_SOURCECI_JOB_TOKEN权限有限，不能直接用来clone别的私有项目，跨项目拉代码要用deploy token- shell执行器没有隔离环境，
CI_DISPOSABLE_ENVIRONMENT=false - 变量展开：默认会递归展开；掩码密钥建议关闭「变量展开」