glab-artifact-registry

glab artifact-registry

将当前启用的 GitLab 凭据换取为短期 Artifact Registry 访问令牌。此命令组也接受 glab ar 别名。此命令组处于实验阶段；在将其用于持久化自动化之前，请核对实时帮助信息和目标 GitLab 实例。

前提条件

• GitLab Enterprise Edition 19.1 或更高版本。
• 实例管理员已启用 gate_token_exchange_endpoint 功能标志。
• glab 已通过身份验证，可用于预期的主机名。

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

先检查访问权限

status 会执行令牌交换，并打印非机密的身份元数据：签发方、主体、受众和过期时间。每次检查都会在服务器端生成一个令牌并立即丢弃；自动化场景优先使用 JSON，且不要在紧密循环中调用此命令。

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

# Extract only non-secret expiry metadata
glab artifact-registry status \
  --hostname gitlab.example.com \
  --output json \
  --jq '.expires_at'

在为其他进程请求令牌之前，请确认签发方、主体和受众分别对应预期的实例、操作者和注册表。

请求短期令牌

文本输出会将纯令牌写入 stdout，方便 shell 捕获或通过管道传递。默认有效期为 15 分钟；有效期可设为 1 秒至 12 小时。请使用足以完成操作的最短有效期。

# Avoid command tracing and keep the token only in a process-local variable
set +x
artifact_token="$(glab artifact-registry get-token \
  --hostname gitlab.example.com \
  --duration 15m)"

# Feed via stdin, not as a command-line argument. Obtain the registry host and
# required username from the target registry's documentation or administrator.
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 垫片，并在 Docker 针对各个注册表的 credHelpers 中注册 glab。
• --maven 会向 ~/.m2/settings.xml 写入一个 <server> 块，以 --registry-alias 为键；使用该配置的 <repository> 必须使用相同的 <id>。
• --gradle 会将 {alias}Url、{alias}Username 和 {alias}Password 写入 ~/.gradle/gradle.properties，其中 {alias} 是 --registry-alias。
• --npm 会向 ~/.npmrc 写入 //{host}{path}/:_authToken 条目；你仍须配置 registry= 或 @scope:registry=，以指定 npm 使用的注册表。
• --yarn 会在 ~/.yarnrc.yml 中配置 Yarn 2 或更高版本：npmRegistries 条目包含 npmAuthToken 和 npmAlwaysAuth。需另行设置匹配的 npmRegistryServer。Yarn 1 请使用 --npm。现有的 npmScopes 凭据可能会覆盖注册表令牌；请查看警告，并在修改前检查作用域。重写 YAML 可能会改变格式。
• --sbt 会向 ~/.sbt/1.0/credentials.sbt 写入一行 credentials +=；使用自定义全局基础目录安装的 sbt 可能不会读取该文件。

# Inspect the intended Docker config and stored GitLab identity first
printf 'Docker config: %s\n' "${DOCKER_CONFIG:-$HOME/.docker}/config.json"
glab auth status --hostname gitlab.example.com

# Configure only the verified Artifact Registry hostname
glab artifact-registry login \
  --hostname gitlab.example.com \
  --docker \
  --registry registry.example.com

# Configure Maven for a two-hour token
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、Yarn 和 sbt，--registry 通常是 URL。
• Docker 每次拉取或推送都会换取新令牌，因此 --duration 不适用。Maven、Gradle、npm、Yarn 和 sbt 会收到一个静态令牌；请在 --duration 到期前重新运行该命令。
• Docker 助手子进程会有意忽略 GITLAB_TOKEN。它通常会读取由 glab auth login 保存的令牌；在 GitLab CI 作业中，如果通过 GLAB_ENABLE_CI_AUTOLOGIN=true 启用了 CI 自动登录，它也会使用 CI_JOB_TOKEN。Maven、Gradle、npm、Yarn 和 sbt 的登录流程可以读取 GITLAB_TOKEN，因为 glab 会将换取的令牌写入各工具的配置文件。
• 仅当注册表确实由 GitLab Artifact Registry 提供支持时才使用此功能。错误地将普通容器注册表归类为该类型，可能导致每次拉取都失败，因为换取的 Artifact Registry 令牌具有优先权。
• 写入前请检查目标配置路径：${DOCKER_CONFIG:-$HOME/.docker}/config.json、~/.m2/settings.xml、~/.gradle/gradle.properties、~/.npmrc、~/.yarnrc.yml 或 ~/.sbt/1.0/credentials.sbt。
• --registry-alias 仅适用于 Maven 和 Gradle。对于 Gradle，请选择在构建脚本中有效的标识符作为别名；推导出的默认值可能包含连字符。
• 对同一注册表重新运行该命令会刷新或替换匹配的条目。配置完成后，请针对目标主机执行非破坏性的包管理器操作进行测试，同时不要打印凭据。

故障排查

• **不受支持或未找到：**请与实例管理员确认 GitLab EE 19.1+ 以及 gate_token_exchange_endpoint 功能标志。
• **颁发者／主题／受众错误：**请停止操作；重新检查 --hostname、环境令牌优先级，以及 glab auth status --hostname <host>。
• **拒绝了有效期：**请使用介于 1s 和 12h 之间的 Go 风格时长。
• **令牌已过期：**请申请新的短期令牌；不要持久化旧令牌或尝试刷新旧令牌。
• **Docker 设置期间出现已保存令牌错误：**请运行 glab auth login --hostname <host>；Docker 助手不会使用仅存在于环境中的令牌。
• **凭据助手冲突：**请检查 Docker 现有的 credHelpers 条目，并保留当前助手，除非操作员明确批准迁移。
• **构建工具仍未通过身份验证：**请确认该工具读取的是 glab artifact-registry login 写入的文件，并且其注册表 URL 或仓库 ID 与写入的键匹配。

请参阅 references/commands.md 查看已记录的命令帮助。