SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场glab-artifact-registry

glab-artifact-registry

部署与运维

查看项目

更新于 10-16 02:09

技能介绍

用途

glab-artifact-registry 是 glab（GitLab CLI）中的命令组，用于把当前活跃的 GitLab 凭据交换为短期的 Artifact Registry 访问令牌、验证令牌身份，以及为包管理器配置认证。命令组别名可写作 glab ar。该命令组为实验性功能，在用于持久化自动化之前应核实实际帮助信息与目标 GitLab 实例。

前置条件

  • GitLab Enterprise Edition 19.1 或更高版本。
  • 实例管理员已启用 gate_token_exchange_endpoint 功能标志。
  • glab 已对预期主机完成身份验证。

令牌是临时的，但仍是凭据。切勿将其打印在日志中、存储在仓库里、包含在命令参数中，或粘贴到 issue/MR 内容里。

主要能力

先检查访问权限

status 会执行令牌交换并打印非机密的身份元数据：issuer、subject、audience 和 expiry。每次检查都会在服务端铸造一个令牌并立即丢弃；面向自动化建议使用 JSON，但不要在紧凑循环中调用。

glab artifact-registry status --hostname gitlab.example.com --output json

只提取非机密的过期元数据：

glab artifact-registry status \
  --hostname gitlab.example.com \
  --output json \
  --jq '.expires_at'

在为其他进程请求令牌之前，先确认 issuer、subject 和 audience 指向预期的实例、操作者和 registry。

请求短期令牌

文本输出会把裸令牌写到 stdout，便于 shell 捕获或管道传递。默认时长为 15 分钟；可接受时长为 1 秒至 12 小时。请使用能覆盖操作的最短时长。

# 避免命令追踪，仅将令牌保存在进程内局部变量中
set +x
artifact_token="$(glab artifact-registry get-token \
  --hostname gitlab.example.com \
  --duration 15m)"

# 通过 stdin 传入，而不是作为命令行参数。从目标 registry 的文档或
# 管理员处获取 registry 主机与所需用户名。
printf '%s' "$artifact_token" | \
  docker login <artifact-registry-host> \
    --username '<registry-username>' \
    --password-stdin
unset artifact_token

仅当消费方还需要过期时间时才使用 --output json。由于 JSON 文档包含令牌，应将其视为机密。不要使用会把令牌打印到日志中的 --jq 表达式。

使用方式：配置包管理器认证

glab artifact-registry login 每次运行只配置一个包管理器：

  • --docker 安装 docker-credential-glab shim，并在 Docker 的按 registry credHelpers 中注册 glab。
  • --maven 向 ~/.m2/settings.xml 写入一个 <server> 块，以 --registry-alias 为键；消费端 <repository> 必须使用相同的 <id>。
  • --gradle 向 ~/.gradle/gradle.properties 写入 {alias}Url、{alias}Username 和 {alias}Password，其中 {alias} 为 --registry-alias。
  • --npm 向 ~/.npmrc 写入 //{host}{path}/:_authToken 条目；你仍需配置 registry= 或 @scope:registry= 以让 npm 指向该 registry。
  • --sbt 向 ~/.sbt/1.0/credentials.sbt 写入一行 credentials +=；使用自定义全局 base 的 sbt 安装可能不会读取该文件。
# 先检查预期的 Docker 配置与已存储的 GitLab 身份
printf 'Docker config: %s\n' "${DOCKER_CONFIG:-$HOME/.docker}/config.json"
glab auth status --hostname gitlab.example.com

# 仅配置经核实的 Artifact Registry 主机名
glab artifact-registry login \
  --hostname gitlab.example.com \
  --docker \
  --registry registry.example.com

# 为 Maven 配置两小时有效期的令牌
glab artifact-registry login \
  --hostname gitlab.example.com \
  --maven \
  --registry https://ar.example.com \
  --registry-alias gitlab-ar \
  --duration 2h

适用场景与限制

安全与兼容性规则：

  • 对于 --docker，--registry 必须是裸主机名，可选带端口。对于 Maven、Gradle、npm 和 sbt，--registry 通常是 URL。
  • Docker 在每次拉取或推送时兑换一个新令牌，因此 --duration 不适用。Maven、Gradle、npm 和 sbt 会收到一个静态令牌；需在 --duration 到期前重新运行命令。
  • Docker 辅助子进程有意忽略 GITLAB_TOKEN。它通常读取由 glab auth login 存储的令牌；在 GitLab CI 作业中，当通过 GLAB_ENABLE_CI_AUTOLOGIN=true 启用 CI 自动登录时，它也遵循 CI_JOB_TOKEN。Maven、Gradle、npm 和 sbt 的登录路径可以读取 GITLAB_TOKEN，因为 glab 会把交换后的令牌写入各工具的配置文件。
  • 仅对确实由 GitLab Artifact Registry 支撑的 registry 使用此功能。误将普通容器 registry 归类，可能使每次拉取都失败，因为交换得到的 Artifact Registry 令牌会优先。
  • 写入前请检查目标配置路径：${DOCKER_CONFIG:-$HOME/.docker}/config.json、~/.m2/settings.xml、~/.gradle/gradle.properties、~/.npmrc 或 ~/.sbt/1.0/credentials.sbt。
  • --registry-alias 仅适用于 Maven 和 Gradle。对于 Gradle，请选择在构建脚本中为合法标识符的别名；派生出的默认值可能包含连字符。
  • 对同一 registry 重新运行命令会刷新或替换匹配的条目。配置完成后，针对预期主机测试一个非破坏性的包管理器操作，且不要打印凭据。

故障排查

  • 不支持或未找到：请与实例管理员核实 GitLab EE 19.1+ 与 gate_token_exchange_endpoint 功能标志。
  • issuer/subject/audience 错误：停止操作；重新检查 --hostname、环境变量令牌优先级以及 glab auth status --hostname <host>。
  • 时长被拒绝：使用 1s 至 12h 之间的 Go 风格时长。
  • 令牌过期：请求一个新的短期令牌；不要持久化或尝试刷新旧令牌。
  • Docker 设置期间出现存储令牌错误：运行 glab auth login --hostname <host>；仅环境变量的令牌不会被 Docker 辅助程序使用。
  • 凭据助手冲突：检查 Docker 现有的 credHelpers 条目，除非操作者明确批准迁移，否则保留当前助手。
  • 构建工具仍未通过认证：核实该工具读取的是 glab artifact-registry login 写入的文件，且其 registry URL 或 repository ID 与写入的键匹配。

命令帮助采集内容见 references/commands.md。