mcpField
G
glab-auth

glab-auth

github.com/vince-winkintel开发49132 次安装1 天前更新
代码仓库

关于 glab-auth

glab-auth 是用于管理 GitLab CLI 认证的技能，面向使用 glab 连接各类 GitLab 主机的个人与自动化流程。内容涵盖登录、凭据存储、状态检查和身份隔离。

主要功能

  1. 01交互式与非交互式登录
  2. 02按主机查看 JSON 认证状态
  3. 03设置 Git 凭据助手
  4. 04使用密钥环或配置文件存储凭据
  5. 05多账户身份隔离注意事项

适用场景

  1. 01为 GitLab 主机配置 glab
  2. 02在自动化中检查认证状态
  3. 03配置 HTTP(S) Git 凭据访问
  4. 04区分 Agent 执行 GitLab 写入时的身份

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vince-winkintel/gitlab-cli-skills --skill glab-auth

安装后在 Claude Code 中输入/glab-auth确认已加载。

附带文件references/commands.md

详细介绍

glab auth

管理 GitLab CLI 身份验证。

非交互式 Git 凭据助手

glab auth login --setup-git-credential-helper 会将 glab 配置为特定主机的 Git 凭据助手，且不会提示用户。此操作会更改该主机的全局 Git 配置，因此除了登录之外，也要取得对这项配置更改的批准。此设置适用于 HTTP(S)；即使偏好使用 SSH，也仍会注册 HTTPS 助手。应优先使用 --stdin，而不是将令牌放入命令参数：

glab auth login --hostname gitlab.example.com --stdin --setup-git-credential-helper < token.txt

请将获准使用的令牌文件保存在 Git 仓库之外，并避免写入日志。缺失的密钥环条目会按常规凭据解析流程处理；密钥环锁定、访问遭拒或不可用时会报告错误。没有可用令牌时，请针对目标主机重新进行身份验证；不要悄悄切换身份或降低存储安全性。

快速入门

# Interactive login
glab auth login

# Browser/OAuth login without the prompt
glab auth login --hostname gitlab.com --web

# Check current auth status
glab auth status

# Login to different instance
glab auth login --hostname gitlab.company.com

# Logout
glab auth logout

工作流

机器可读的身份验证状态
glab auth status --hostname gitlab.example.com --output json
glab auth status --all --output json
glab auth status --all --output json --jq '.hosts[] | {host, state, user}'

JSON 包含一个 hosts 数组，其中列出每个主机的状态、用户（如有）、端点、协议、令牌来源、警告和错误元数据。数组中不会包含令牌本身；使用 JSON 输出时会拒绝 --show-token。不要将省略的可选字段误认为空凭据。在执行任何写入操作之前，请检查退出状态和每个主机的状态，并使用 glab api user 独立验证预期的操作身份。请将 --jq 与 --output json 配合使用。

首次设置
  1. 运行 glab auth login
  2. 选择身份验证方式（令牌或浏览器）
  3. 按照提示设置你的 GitLab 实例
  4. 使用 glab auth status 验证

glab auth login 支持完整的设置流程：

  • --api-host：为可自托管实例显式设置不同的 API/网页端点
  • --ssh-hostname：为可自托管实例显式设置不同的 SSH 端点
  • --web：跳过登录类型提示，直接使用浏览器/OAuth 身份验证
  • --container-registry-domains：在登录时预先配置注册表/依赖代理域名

示例：API 主机名为 gitlab.company.com，SSH 主机名为 ssh.company.com

对于个人访问令牌，glab 至少需要 api 和 write_repository。GitLab 18.9 引入了 https://<host>/-/user_settings/personal_access_tokens/legacy/new?scopes=api,write_repository；较早版本中不存在此路由。GitLab 18.8 及更早版本则使用 https://<host>/-/user_settings/personal_access_tokens?scopes=api,write_repository。请使用目标实例对应的 URL，不要假设较旧的自托管服务上存在当前 GitLab.com 的路由。

在非交互式登录中，如果省略 --hostname，则按以下顺序确定目标：基础仓库的 GitLab 远程地址、GITLAB_HOST、配置中的 host，然后是 gitlab.com。写入凭据时，如果当前仓库或环境并非有意作为权威来源，请优先显式指定 --hostname。

在交互式登录中，由环境提供的配置值只会在匹配的流程中预先回答相应的设置问题。GITLAB_HOST 会在检测远程地址前选择实例。如果主机名来自 --hostname 或 GITLAB_HOST，GITLAB_API_HOST 和 GITLAB_SSH_HOST 会跳过对应的端点提示；如果你在实例菜单中选择“GitLab Self-Managed or GitLab Dedicated instance”路径，除非提供 --api-host 和 --ssh-hostname，否则 glab 仍会提示输入端点主机名。GLAB_CONTAINER_REGISTRY_DOMAINS、GLAB_GIT_PROTOCOL 和 GLAB_API_PROTOCOL 会跳过各自的注册表域名和协议提示。对于一次性的凭据写入，显式命令标志更清晰；如果 shell 状态未受到严格控制，应优先使用这些标志。

对于 GitLab Self-Managed 或 GitLab Dedicated 的浏览器/OAuth 登录，如果尚未配置 OAuth 应用程序 ID，glab 现在会引导你完成交互式设置。你可以选择粘贴现有的 Application ID，或打印供实例/群组管理员使用的确切注册信息。选择“show me what an admin needs to create”只会打印重定向 URI、作用域和 Confidential: off 要求，然后以非零状态退出本次登录尝试，并显示相同的“先设置 client_id”错误。管理员创建应用程序后，请通过 glab config set client_id <client_id> -g --host <hostname> 保存 ID，或导出 GITLAB_CLIENT_ID，然后重新运行登录；打印注册信息并不能继续当前登录尝试。切勿在 Application ID 提示中粘贴应用程序密钥。只有 OAuth 往返成功后，新粘贴的 ID 才会被持久化。在非交互式环境中，请使用 glab config set client_id <client_id> -g --host <hostname> 显式预先配置，或提供 GITLAB_CLIENT_ID。

登录标志示例

通过 --token 或 --stdin 进行令牌登录时，也会为所选主机持久化容器注册表域名。解析时优先使用显式指定的 --container-registry-domains，其次是已配置的值（包括由环境提供的配置），最后才是根据主机名推导的默认值。这样可以在重新登录时保留自定义域名，并使 Docker 凭据助手能够使用这些域名。在配置 Docker 之前，请使用 glab config get container_registry_domains --host <hostname> 进行验证。此持久化行为适用于个人令牌流程；不要假设独立的 --job-token 流程具有相同的设置行为。

# Personal-token login with explicit registry domains; keep the token file outside Git
glab auth login --hostname gitlab.company.com --stdin \
  --api-protocol https --git-protocol ssh \
  --container-registry-domains "registry.gitlab.company.com,gitlab.company.com" \
  < approved-token-file
glab config get container_registry_domains --host gitlab.company.com

# Self-managed GitLab with separate API and SSH endpoints
glab auth login \
  --hostname gitlab.company.com \
  --ssh-hostname ssh.company.com

# Skip prompts and go straight to browser/OAuth auth
glab auth login --hostname gitlab.com --web

# Preconfigure multiple registry / dependency proxy domains during login
glab auth login \
  --hostname gitlab.com \
  --web \
  --container-registry-domains "registry.gitlab.com,gitlab.com"

# Supply every self-managed endpoint so only browser authorization remains interactive
glab auth login --hostname gitlab.example.com --web \
  --api-host gitlab.example.com --ssh-hostname gitlab.example.com \
  --api-protocol https --git-protocol ssh \
  --container-registry-domains registry.gitlab.example.com

# Explicitly opt out of keyring storage (stores the token as plaintext)
glab auth login --hostname gitlab.company.com --insecure-storage \
  --stdin < approved-token-file
凭据存储

在普通工作站上，如果操作系统密钥环可用，glab auth login 默认会将凭据存储在其中：macOS Keychain、Windows Credential Manager 或 Linux Secret Service。旧的 --use-keyring 标志已弃用，因为密钥环存储现在是默认方式。重新运行登录会将之前以明文形式存储在配置文件中的凭据迁移到密钥环。

仅在明确需要将凭据以明文形式存储在配置文件中，且接受相应风险时，才使用 --insecure-storage。如果没有可用的密钥环后端，glab 会发出警告并回退到配置文件存储。在 CI 中（设置了 GITLAB_CI 或 CI），glab 默认使用配置文件存储，因为密钥环通常不可用或是临时的；建议使用环境凭据，而不要在其中持久化登录信息。

如果密钥环已锁定、不可用或拒绝访问，glab 会直接报告凭据读取失败。请修复密钥环访问问题或重新进行身份验证，而不要将由此产生的错误视为令牌无效。

glab 会在刷新令牌前检查能否保存刷新的 OAuth 凭据，并在并发运行的 glab 进程之间串行写入凭据。如果多个 Agent 或 Shell 共用一个配置目录，建议为每个使用者使用单独的配置目录以实现隔离，但不要在 glab 外部添加文件锁。

OAuth 访问令牌会提前五分钟刷新，而不是等到令牌即将过期。如果令牌仍可使用，但无法保存刷新的凭据，glab 会继续使用当前令牌，而不会因保存探测而立即导致服务中断。对于子文件夹下的自托管实例，刷新请求会使用已配置的子文件夹；诊断令牌刷新 URL 时，请保留准确的 subfolder 主机设置。

在 Claude Code 等沙箱中，必须允许 glab 写入 glab config path --dir 返回的目录，而不仅仅是 config.yml 文件。glab 会在配置文件旁写入临时文件，然后替换原文件。在 snap 安装中，如果需要加密凭据存储，请使用 sudo snap connect glab:password-manager-service 连接密钥环访问；否则，glab auth login 可以回退到明文配置文件存储。

以交互方式重新进行身份验证时，glab 会保留已保存的各主机配置值，例如自定义 API 主机、SSH 主机和容器注册表域名，除非你使用标志或提示明确覆盖这些值。重新进行身份验证后，请先核实这些值，而不要提前删除配置：

glab config get api_host --host gitlab.company.com
glab config get ssh_host --host gitlab.company.com
glab config get container_registry_domains --host gitlab.company.com

非交互式登录也会将明确提供的 --git-protocol 和 --api-protocol 值持久化到主机配置中。这适用于令牌/标准输入以及其他无提示登录方式，因此自动化流程可以在同一次登录操作中配置协议，而无需之后再编辑配置。依赖这些设置前，请先核实生成的主机条目：

glab auth login --hostname gitlab.company.com --stdin \
  --git-protocol ssh --api-protocol https < approved-token-file
glab config get git_protocol --host gitlab.company.com
glab config get api_protocol --host gitlab.company.com

请将令牌文件保存在版本控制之外，并且不要打印其内容。

CI 自动登录： GLAB_ENABLE_CI_AUTOLOGIN=true 可让 glab 在 GitLab CI/CD 中使用 CI_JOB_TOKEN，而无需保存登录信息。GITLAB_TOKEN、GITLAB_ACCESS_TOKEN 和 OAUTH_TOKEN 的优先级仍然更高，因此如果预期使用的凭据是 CI_JOB_TOKEN，请将这些变量留空。如果命令需要项目、群组或个人访问令牌，请改用显式环境令牌。

Agent 化和多账户设置

如果你需要让不同的 Agent 显示为不同的 GitLab 用户，请使用不同的 GitLab 机器人／服务账户。在同一个 GitLab 用户下使用多个 PAT 适用于令牌轮换或权限范围隔离，但不会产生不同的可见身份。

对于由操作者撰写的 GitLab 评论、回复、批准及其他写入操作，请使用操作者身份。只有当某项 GitLab 操作明确属于某个 Agent 自己的工作成果时，才使用该 Agent 身份。首次写入前，请先选定预期显示的操作者。

一个良好的操作模式是每个操作者使用一个环境变量文件：

# ~/.config/openclaw/env/gitlab-reviewer.env
GITLAB_TOKEN=glpat-...
GITLAB_HOST=gitlab.com

请将这些环境变量文件保存在版本控制之外，限制其权限（例如 chmod 600），留意备份可能造成的暴露风险，并优先使用遵循最小权限原则的机器人／服务账户令牌。在重复使用的 shell 中，请先清除过期的 GitLab 身份验证变量，或启动一个新的 shell。

如果文件使用普通的 KEY=value 行，请在运行 glab 前加载并导出变量：

unset GITLAB_TOKEN GITLAB_ACCESS_TOKEN OAUTH_TOKEN GITLAB_HOST
set -a
source ~/.config/openclaw/env/gitlab-<actor>.env
set +a

这很重要，原因如下：

  • 普通的 source 不一定会将变量导出给子进程
  • glab 只能读取已导出的环境变量
  • 如果 glab 无法读取环境令牌，它可能会静默回退到当前全局配置文件中存储的共享身份验证信息
  • 如果同一 shell／会话中先前加载过另一个环境变量文件，身份可能会以不安全的方式保持不变，除非你有意切换并进行验证

这种回退／共享身份验证行为对用户来说很方便，但在多 Agent 自动化场景中，可能导致错误的 GitLab 账户发表评论、创建 MR 或批准工作。

任何 GitLab 写入操作前的必要预检

在进行任何 GitLab 写入操作前立即运行此命令，包括 glab mr note、提交评审或批准、回复讨论串，以及任何 glab api POST／PATCH／PUT／DELETE 调用：

glab auth status --hostname "$GITLAB_HOST"
glab api --hostname "$GITLAB_HOST" user

这假定目标操作者的环境变量文件已为你打算修改的确切 GitLab 实例设置 GITLAB_HOST。只有当两个命令都明确显示该主机上的预期可见操作者时，才进行写入。

错误身份的补救措施

如果评论或回复是以错误身份发布的：

  1. 停止发布。
  2. 如需清理，删除错误的评论或回复。
  3. 执行 unset GITLAB_TOKEN GITLAB_ACCESS_TOKEN OAUTH_TOKEN GITLAB_HOST，或启动一个新的 shell。
  4. 使用 set -a; source ...; set +a 加载正确的环境变量文件。
  5. 重新运行 glab auth status --hostname "$GITLAB_HOST" 和 glab api --hostname "$GITLAB_HOST" user。
  6. 以正确的操作者身份重新发布。
  7. 确认替换后的消息所在讨论串不再显示错误的可见作者。

如果错误身份的写入更改了评论或回复之外的状态，请按上述方法重新进行身份验证，然后以正确的操作者身份和主机，使用相应的 GitLab 撤销操作来恢复该写入，例如取消批准 MR，或针对具体被更改的资源，执行用于补偿的 glab api --hostname "$GITLAB_HOST" 变更。

切换账户／实例

  1. 退出当前账户：

    glab auth logout

  2. 登录新实例：

    glab auth login --hostname gitlab.company.com

  3. 验证：

    glab auth status --hostname gitlab.company.com
Docker 注册表访问

  1. 配置 Docker 辅助程序：

    glab auth configure-docker

  2. 验证 Docker 能否进行身份验证：

    docker login registry.gitlab.com

  3. 拉取私有镜像：

    docker pull registry.gitlab.com/group/project/image:tag

configure-docker 只会为已配置的 GitLab 注册表域添加 glab。 它会保留无关的 Docker 凭据辅助程序，并拒绝替换已分配给同一域的其他辅助程序。如果某个域有来自 docker login 的旧凭据，glab 会警告辅助程序的优先级更高；确认基于辅助程序的访问正常后，使用准确的建议命令 docker logout <domain> 删除被遮蔽的条目。手动修复冲突前，请备份并检查 $DOCKER_CONFIG/config.json。

glab 通常会将辅助脚本安装在 glab 二进制文件旁边。如果该目录不可写，它会退而使用 ~/.local/bin，然后选择 PATH 上另一个已存在且可写的目录；如果所选目录不在 PATH 中，请按提示的路径说明操作后再测试 Docker。不要仅为将辅助程序放在那里，就让 glab 安装目录变为广泛可写。

故障排查

“401 Unauthorized” 错误：

  • 检查状态：glab auth status
  • 确认令牌尚未过期（检查 GitLab 设置）
  • 重新进行身份验证：glab auth login

更改身份验证方式后，重新登录似乎仍然卡住：

  • 如果你从浏览器/OAuth 登录切换为基于令牌的登录，而 glab 似乎仍在使用过期的已存储凭据，请再次运行 glab auth login，不要直接认定必须手动编辑配置。
  • 重新登录后，先用 glab auth status 验证，再重试失败的命令。

环境令牌身份验证失败：

  • 如果已导出 GITLAB_TOKEN、GITLAB_ACCESS_TOKEN 或 OAUTH_TOKEN，它会覆盖已存储的凭据。
  • 无论是否有已存储的 OAuth 配置，GITLAB_TOKEN 和 GITLAB_ACCESS_TOKEN 都会被视为个人访问令牌，因此临时 PAT 不会继承或刷新已保存的 OAuth 状态。
  • 如果主机配置为使用 OAuth，但环境变量中包含 OAuth 访问令牌，请设置 GLAB_IS_OAUTH2=true；否则，glab 会将环境令牌作为个人访问令牌发送。发生 401 后，glab auth status 会报告此方案不匹配。
  • 如果身份验证突然失败，请先检查是否使用了环境令牌，再判断已保存的登录凭据是否失效。glab auth login 和 glab auth status 会在此优先级规则生效时发出警告。
  • 运行 type glab，判断它是会主动注入令牌的包装器（例如 1Password shell 插件别名），还是普通的可执行文件路径。包装器可能是预期行为，无需处理；如果显示的是普通路径，则令牌来自 shell 配置文件、当前环境或 CI 变量。
  • 这些故障可能影响读取操作和写入操作，而不仅仅是写入前的检查。
  • 在进行任何 GitLab 写入操作前，用 glab auth status 和 glab api user 验证当前使用的身份和令牌来源。
  • 在多 Agent shell 中，重试前请有意重新加载所需的环境文件：set -a; source ...; set +a。

自托管 OAuth URL 或刷新问题：

  • 使用完整的已配置主机名和子文件夹重新进行身份验证；浏览器 OAuth 会在授权 URL 中包含已配置的子文件夹。
  • OAuth 令牌刷新也会使用已配置的子文件夹；在假定令牌端点位于主机根目录前，请先检查 glab config get subfolder --host <host>。
  • 当可以保存凭据时，过期时间在五分钟宽限期内的已存储 OAuth 令牌会主动刷新。
  • 如果重新进行身份验证时响应中未包含替换用的刷新令牌，则会保留现有刷新令牌，而不是将其清除。
  • 如果刷新时出现 invalid_grant，请重新运行 glab auth login；已撤销或过期的 OAuth 授权，或此前保存凭据失败，都可能导致已存储的 OAuth 凭据过期。
  • 如果在沙盒中刷新 OAuth 失败，并出现凭据保存错误，请为 glab config path --dir 授予写入权限，然后重新进行身份验证。通常，重试同一个过期令牌无法修复已保存的凭据。
  • 对于通过个人访问令牌进行身份验证的主机，Docker 和其他辅助工具会跳过 OAuth 刷新；排查 OAuth 状态前，请先检查令牌类型。

多个实例：

  • 使用 --hostname 标志指定实例
  • 每个实例都有独立的身份验证

Docker 身份验证失败：

  • 重新运行：glab auth configure-docker
  • 检查 Docker 配置：cat ~/.docker/config.json
  • 确认已设置辅助程序："credHelpers": { "registry.gitlab.com": "glab-cli" }

子命令

详细的标志说明请参见 references/commands.md：

  • login - 使用 GitLab 实例进行身份验证
  • logout - 从 GitLab 实例登出
  • status - 查看身份验证状态
  • configure-docker - 配置 Docker 以使用 GitLab 注册表
  • docker-helper - Docker 凭据辅助程序
  • dpop-gen - 生成 DPoP 令牌

相关技能

初始设置：

  • 完成身份验证后，参阅 glab-config 设置 CLI 默认值
  • 参阅 glab-ssh-key 管理 SSH 密钥
  • 参阅 glab-gpg-key 设置提交签名

仓库操作：

  • 参阅 glab-repo 克隆仓库
  • 首次克隆或推送前需要先完成身份验证

评论

支持 Markdown