gitlab-variable

CI/CD 变量技能

使用 glab CLI 管理 GitLab 的 CI/CD 变量。

快速参考

操作	命令	风险
列出变量	glab variable list	-
获取变量	glab variable get <key>	-
设置变量	glab variable set <key> <value>	⚠️
更新变量	glab variable update <key> <value>	⚠️
删除变量	glab variable delete <key>	⚠️⚠️
导出变量	glab variable export	-

风险图例：- 安全 | ⚠️ 谨慎 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况下使用：

• 用户想要管理 CI/CD 变量
• 用户提到“变量”“密钥”“环境变量”“CI 变量”“环境变量”
• 用户想要配置构建/部署设置

以下情况绝不要使用：

• 用户想要运行流水线（使用 gitlab-ci）
• 用户想要在本地管理 .env 文件（使用文件操作）

可用命令

列出变量

glab variable list [options]

选项：

标志	描述
-g, --group=<group>	列出群组级变量
-P, --per-page=<n>	每页结果数

示例：

# List project variables
glab variable list

# List group variables
glab variable list -g mygroup

获取变量

glab variable get <key> [options]

选项：

标志	描述
-g, --group=<group>	从群组级获取
-s, --scope=<scope>	变量范围/环境

示例：

# Get variable value
glab variable get API_KEY

# Get scoped variable
glab variable get DATABASE_URL --scope=production

设置变量

glab variable set <key> <value> [options]

选项：

标志	描述
-g, --group=<group>	在群组级设置
-m, --masked	在日志中隐藏值
-p, --protected	仅在受保护的分支中可用
-r, --raw	值为原始值（不展开）
-s, --scope=<scope>	变量范围/环境
-t, --type=<type>	变量类型：env_var、file

示例：

# Set simple variable
glab variable set API_URL "https://api.example.com"

# Set masked secret
glab variable set API_KEY "secret123" --masked

# Set protected variable (only on protected branches)
glab variable set DEPLOY_KEY "key123" --protected --masked

# Set scoped variable for production
glab variable set DATABASE_URL "postgres://prod..." --scope=production

# Set file type variable
glab variable set CONFIG_FILE "$(cat config.json)" --type=file

# Set group variable
glab variable set SHARED_SECRET "secret" -g mygroup --masked

更新变量

glab variable update <key> <value> [options]

选项与 set 相同。更新现有变量。

示例：

# Update variable value
glab variable update API_KEY "new-secret" --masked

# Update and change scope
glab variable update DATABASE_URL "new-url" --scope=staging

删除变量

glab variable delete <key> [options]

选项：

标志	描述
-g, --group=<group>	从群组级删除
-s, --scope=<scope>	变量范围

警告： 此操作会永久删除该变量。

示例：

# Delete variable
glab variable delete OLD_API_KEY

# Delete scoped variable
glab variable delete DATABASE_URL --scope=staging

导出变量

glab variable export [options]

以 dotenv 格式导出变量。

示例：

# Export to stdout
glab variable export

# Export to file
glab variable export > .env.ci

# Export and source
eval $(glab variable export)

变量类型

类型	用途
env_var	环境变量（默认）
file	将值写入文件，并将路径作为变量公开

变量标志

标志	效果
masked	在作业日志中隐藏值
protected	仅在受保护的分支/标签上可用
raw	不展开变量（用于 JSON 等）

常见工作流

工作流 1：设置部署变量

# Set production secrets
glab variable set PROD_API_KEY "xxx" --protected --masked --scope=production
glab variable set PROD_DB_URL "postgres://..." --protected --masked --scope=production

# Set staging secrets
glab variable set STAGING_API_KEY "xxx" --masked --scope=staging
glab variable set STAGING_DB_URL "postgres://..." --masked --scope=staging

工作流 2：轮换密钥

# 1. List current variables
glab variable list

# 2. Update the secret
glab variable update API_KEY "new-secret-value" --masked

# 3. Trigger a new pipeline to use new secret
glab ci run

工作流 3：设置服务账户

# Store credentials as masked file
glab variable set SERVICE_ACCOUNT_JSON "$(cat service-account.json)" \
  --type=file --protected --masked

# In CI/CD, use $SERVICE_ACCOUNT_JSON as path to the credentials file

工作流 4：配置多环境

# Production (protected + masked)
glab variable set DATABASE_URL "postgres://prod..." --scope=production --protected --masked
glab variable set API_KEY "prod-key" --scope=production --protected --masked

# Staging
glab variable set DATABASE_URL "postgres://staging..." --scope=staging --masked
glab variable set API_KEY "staging-key" --scope=staging --masked

# Development
glab variable set DATABASE_URL "postgres://dev..." --scope=development
glab variable set API_KEY "dev-key" --scope=development

安全最佳实践

1. 始终隐藏密钥：对任何敏感值使用 --masked
2. 保护生产密钥：对生产凭据使用 --protected
3. 使用范围：按环境分隔变量
4. 定期轮换：定期更新密钥
5. 避免记录日志：切勿在 CI 脚本中回显变量值
6. 复杂密钥使用 file 类型：JSON、证书等

故障排除

问题	原因	解决方案
身份验证失败	令牌无效或已过期	运行 glab auth login
找不到变量	键或范围错误	使用 glab variable list 检查
无法查看值	变量已隐藏	无法检索已隐藏的值
权限被拒绝	不是维护者	管理变量需要维护者或更高角色
值被截断	特殊字符	对复杂值使用 --raw 标志

相关文档

• 安全措施
• 快速参考