gitlab-variable

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CI/CD Variable Skill

CI/CD变量管理技能

CI/CD variable management operations for GitLab using the

glab

CLI.

使用

glab

CLI工具对GitLab进行CI/CD变量管理操作。

Quick Reference

快速参考

Operation	Command	Risk
List variables	`glab variable list`	-
Get variable	`glab variable get <key>`	-
Set variable	`glab variable set <key> <value>`	⚠️
Update variable	`glab variable update <key> <value>`	⚠️
Delete variable	`glab variable delete <key>`	⚠️⚠️
Export variables	`glab variable export`	-

Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger

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

风险说明: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用本技能

ALWAYS use when:

User wants to manage CI/CD variables
User mentions "variable", "secret", "env var", "CI variable", "environment variable"
User wants to configure build/deployment settings

NEVER use when:

User wants to run pipelines (use gitlab-ci)
User wants to manage .env files locally (use file operations)

务必在以下场景使用:

用户需要管理CI/CD变量
用户提到“variable”、“secret”、“env var”、“CI variable”、“environment variable”（变量、密钥、环境变量等）
用户需要配置构建/部署设置

请勿在以下场景使用:

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

Available Commands

可用命令

List Variables

列出变量

bash

glab variable list [options]

Options:

Flag	Description
`-g, --group=<group>`	List group-level variables
`-P, --per-page=<n>`	Results per page

Examples:

bash

undefined

bash

glab variable list [options]

选项:

参数	描述
`-g, --group=<group>`	列出组级变量
`-P, --per-page=<n>`	每页显示结果数

示例:

bash

undefined

List project variables

列出项目变量

glab variable list

List group variables

列出组变量

glab variable list -g mygroup

undefined

glab variable list -g mygroup

undefined

Get Variable

获取变量

bash

glab variable get <key> [options]

Options:

Flag	Description
`-g, --group=<group>`	Get from group level
`-s, --scope=<scope>`	Variable scope/environment

Examples:

bash

undefined

bash

glab variable get <key> [options]

选项:

参数	描述
`-g, --group=<group>`	从组级获取变量
`-s, --scope=<scope>`	变量作用域/环境

示例:

bash

undefined

Get variable value

获取变量值

glab variable get API_KEY

Get scoped variable

获取带作用域的变量

glab variable get DATABASE_URL --scope=production

undefined

glab variable get DATABASE_URL --scope=production

undefined

Set Variable

设置变量

bash

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

Options:

Flag	Description
`-g, --group=<group>`	Set at group level
`-m, --masked`	Mask value in logs
`-p, --protected`	Only available in protected branches
`-r, --raw`	Value is raw (no expansion)
`-s, --scope=<scope>`	Variable scope/environment
`-t, --type=<type>`	Variable type: env_var, file

Examples:

bash

undefined

bash

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

选项:

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

示例:

bash

undefined

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

undefined

glab variable set SHARED_SECRET "secret" -g mygroup --masked

undefined

Update Variable

更新变量

bash

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

Same options as

set

. Updates existing variable.

Examples:

bash

undefined

bash

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

选项与

set

命令相同，用于更新现有变量。

示例:

bash

undefined

Update variable value

更新变量值

glab variable update API_KEY "new-secret" --masked

Update and change scope

更新变量并修改作用域

glab variable update DATABASE_URL "new-url" --scope=staging

undefined

glab variable update DATABASE_URL "new-url" --scope=staging

undefined

Delete Variable

删除变量

bash

glab variable delete <key> [options]

Options:

Flag	Description
`-g, --group=<group>`	Delete from group level
`-s, --scope=<scope>`	Variable scope

Warning: This permanently deletes the variable.

Examples:

bash

undefined

bash

glab variable delete <key> [options]

选项:

参数	描述
`-g, --group=<group>`	从组级删除变量
`-s, --scope=<scope>`	变量作用域

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

示例:

bash

undefined

Delete variable

删除变量

glab variable delete OLD_API_KEY

Delete scoped variable

删除带作用域的变量

glab variable delete DATABASE_URL --scope=staging

undefined

glab variable delete DATABASE_URL --scope=staging

undefined

Export Variables

导出变量

bash

glab variable export [options]

Export variables in dotenv format.

Examples:

bash

undefined

bash

glab variable export [options]

以dotenv格式导出变量。

示例:

bash

undefined

Export to stdout

导出到标准输出

glab variable export

Export to file

导出到文件

glab variable export > .env.ci

Export and source

导出并加载

eval $(glab variable export)

undefined

eval $(glab variable export)

undefined

Variable Types

变量类型

Type	Use Case
`env_var`	Environment variable (default)
`file`	Write value to file, expose path as variable

类型	使用场景
`env_var`	环境变量（默认）
`file`	将值写入文件，暴露文件路径作为变量

Variable Flags

变量参数

Flag	Effect
`masked`	Value is hidden in job logs
`protected`	Only available on protected branches/tags
`raw`	No variable expansion (use for JSON, etc.)

参数	作用
`masked`	在作业日志中隐藏变量值
`protected`	仅在受保护分支/标签中可用
`raw`	不进行变量展开（适用于JSON等格式）

Common Workflows

常见工作流

Workflow 1: Set Up Deployment Variables

工作流1：配置部署变量

bash

undefined

bash

undefined

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

undefined

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

undefined

Workflow 2: Rotate Secrets

工作流2：轮换密钥

bash

undefined

bash

undefined

1. List current variables

1. 列出当前变量

glab variable list

2. Update the secret

2. 更新密钥

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

3. Trigger a new pipeline to use new secret

3. 触发新流水线以使用新密钥

glab ci run

undefined

glab ci run

undefined

Workflow 3: Set Up Service Account

工作流3：配置服务账号

bash

undefined

bash

undefined

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

在CI/CD中，使用$SERVICE_ACCOUNT_JSON作为凭据文件的路径

undefined

undefined

Workflow 4: Configure Multi-Environment

工作流4：配置多环境变量

bash

undefined

bash

undefined

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

undefined

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

undefined

Security Best Practices

安全最佳实践

Always mask secrets: Use
```
--masked
```
for any sensitive values
Protect production secrets: Use
```
--protected
```
for production credentials
Use scopes: Separate variables by environment
Rotate regularly: Update secrets periodically
Avoid logging: Never echo variable values in CI scripts
Use file type for complex secrets: JSON, certificates, etc.

始终掩码密钥: 对任何敏感值使用
```
--masked
```
参数
保护生产环境密钥: 对生产凭据使用
```
--protected
```
参数
使用作用域: 按环境分离变量
定期轮换: 定期更新密钥
避免日志输出: 切勿在CI脚本中打印变量值
复杂密钥使用文件类型: 适用于JSON、证书等

Troubleshooting

故障排除

Issue	Cause	Solution
Authentication failed	Invalid/expired token	Run `glab auth login`
Variable not found	Wrong key or scope	Check with `glab variable list`
Cannot see value	Variable is masked	Masked values cannot be retrieved
Permission denied	Not maintainer	Need maintainer+ role for variables
Value truncated	Special characters	Use `--raw` flag for complex values

问题	原因	解决方案
认证失败	令牌无效/过期	运行 `glab auth login` 重新认证
变量未找到	密钥或作用域错误	使用 `glab variable list` 检查
无法查看变量值	变量已掩码	掩码变量的值无法被检索
权限不足	非维护者角色	需要维护者及以上角色才能管理变量
值被截断	包含特殊字符	对复杂值使用 `--raw` 参数