gitlab

GitLab 技能

概述

使用此技能检查和更新 GitLab.com 或自托管 GitLab 实例上的合并请求、备注、流水线和作业日志。

此技能是用于 GitLab 任务的仓库本地 Python 工作流，并非官方 GitLab MCP 服务集成接口。

此初始版 hve-core 仅支持 Python。通过 python scripts/gitlab.py 运行 CLI；读取操作优先使用 --fields，以保持输出简洁。

前置条件

此技能需要 Python 3.11 或更高版本。

运行任何命令前，请设置以下环境变量：

变量	必需项	示例	用途
GITLAB_URL	是	https://gitlab.com	GitLab 实例 URL
GITLAB_AUTH_MODE	可选	oauth	oauth 或显式的 legacy-token 兼容模式
GITLAB_OAUTH_CLIENT_ID	OAuth	Application ID	非机密 OAuth 应用 ID；无需客户端密钥
GITLAB_TOKEN	传统模式	glpat-...	仅在 GITLAB_AUTH_MODE=legacy-token 时接受 PAT
GITLAB_PROFILE	否	default	命名的 OAuth 配置
GITLAB_TOKEN_STORE	否	path	OAuth 存储位置覆盖项；在 POSIX 上，其父目录必须仅对所有者开放
GITLAB_ALLOW_INSECURE	否	1	仅允许显式指定的本地回环 HTTP 开发端点
XDG_DATA_HOME	否	path	POSIX 数据根目录，用于默认 OAuth 存储
LOCALAPPDATA	否	path	保留的 Windows 数据根目录；目前 OAuth 持久化在 Windows 上会失败关闭
GITLAB_PROJECT	否	group/project	项目路径或数字项目 ID

如果未设置 GITLAB_PROJECT，脚本会尝试通过 git remote get-url origin 检测项目。如果当前目录不在 git 仓库中，或你想指定其他项目，请显式设置此变量。

运行变量

变量	必需项	用途
GITLAB_AUDIT_LOG	否	JSON Lines 审计日志的路径。设置后，每个请求都会被审计（参见“审计日志”）。
GITLAB_AUDIT_ACTOR	否	覆盖记录的操作者身份（例如，CI 服务主体）。
GITLAB_DEBUG	否	设置为 1，在失败时打印脱敏后的回溯信息。绝不会停用脱敏。

审计日志

设置 GITLAB_AUDIT_LOG 后，脚本会为每个 REST API 和 OAuth 表单请求写入结构化的 JSON Lines 审计记录。审计采用失败关闭和预写方式：

• 在发送请求之前写入 attempt 记录。如果无法写入审计日志，则中止操作，不会向 GitLab 发送任何内容。
• 请求完成后写入 outcome 记录（success 或 error；失败时包含 HTTP 状态码）。

REST 记录包含 UTC 时间戳、操作者、认证模式、规范化来源、 操作、HTTP 方法和事件。OAuth 记录使用范围受限的操作和 失败类型，不包含操作者、来源、客户端、配置文件、代码、正文或自由格式的 错误字段。资源路径、查询、配置文件名称和配置文件内容均不会 记录。可选的审计目标具有较高的操作敏感性，因为来源可能暴露租户或内部主机信息。 请将其放在访问受控的路径下，并且仅在操作需要的期限内保留。令牌和授权标头绝不会写入。请求发出后发生的审计失败会触发警告，但不会更改结果。

凭据轮换

OAuth 是默认方式。注册一个非机密的用户、群组或自托管 实例拥有的应用，并将重定向 URI 设置为 http://127.0.0.1:8766/callback，作用域设置为 api。仅设置 GITLAB_URL 和 GITLAB_OAUTH_CLIENT_ID，然后运行 auth login 或 需要人工协助的 auth device-login。浏览器登录需要轮换刷新 令牌；访问令牌会在过期前刷新，替换令牌会以原子方式存储。设备登录可能会返回仅含访问令牌的配置文件，过期后需要再次进行设备登录。提供方或本地崩溃时仍可能需要重新登录。

在 POSIX 系统上，默认存储路径为 $XDG_DATA_HOME/hve-core/gitlab/gitlab-token.json，若该环境变量未设置，则回退到 ~/.local/share/hve-core/gitlab/gitlab-token.json。 POSIX 系统上的存储文件和锁文件权限为 0600，并位于仅所有者可访问的专用 目录中。由于 Python 3.11 的权限位无法强制执行仅所有者可访问的 DACL，因此在 Windows 上，OAuth 配置文件持久化会失败关闭。在受保护的 OAuth 后端可用之前，请在 Windows 上显式使用 legacy-token 模式。

仍可通过 GITLAB_AUTH_MODE=legacy-token 使用 PAT 认证。设备授权需要用户在支持浏览器的设备上批准，不适用于无人值守的工作负载身份。

快速开始

导出环境变量，然后使用 --fields 运行读取命令。

export GITLAB_URL="https://gitlab.com"
export GITLAB_OAUTH_CLIENT_ID="your-application-id"
export GITLAB_PROJECT="group/project"

python scripts/gitlab.py auth login
python scripts/gitlab.py mr-list opened --fields iid,title,author.name

读取已知管道的作业：

python scripts/gitlab.py pipeline-jobs 12345 --fields id,name,status,stage

参数参考

通用选项

参数	适用命令	示例	说明
--fields	mr-list、mr-get、mr-notes、pipeline-get、pipeline-jobs	--fields iid,title,state	使用点号表示法提取特定字段，并以简洁的表格或键值形式输出

命令

命令	参数	描述
auth login	无	使用 Authorization Code 和 PKCE 进行身份验证
auth device-login	无	通过人工协助的设备授权进行身份验证
auth status	无	打印不含密钥的本地配置文件状态
auth logout	无	删除一个本地配置文件，不撤销服务端授权
mr-list	[state] [max]	列出合并请求，默认显示所有状态和 20 条结果
mr-get	<mr-iid>	根据项目范围内的 IID 获取一个合并请求
mr-create	<json> 或 stdin	根据 JSON 载荷创建合并请求
mr-update	<mr-iid> <json> 或 stdin	根据 JSON 载荷更新合并请求字段
mr-comment	<mr-iid> <body> 或 stdin	为合并请求添加评论
mr-notes	<mr-iid> [max]	列出合并请求备注；使用 --fields 时排除系统备注
pipeline-get	<pipeline-id>	根据数字 ID 获取一个流水线
pipeline-run	<branch-or-tag>	为分支或标签触发流水线
pipeline-jobs	<pipeline-id>	列出流水线的作业
job-log	<job-id>	打印作业的原始日志输出

脚本参考

列出最近的未关闭合并请求：

python scripts/gitlab.py mr-list opened --fields iid,title,author.name,user_notes_count

获取一个合并请求：

python scripts/gitlab.py mr-get 42 --fields iid,title,state,source_branch,target_branch

通过内联 JSON 创建合并请求：

python scripts/gitlab.py mr-create '{
  "source_branch": "feature/add-auth",
  "target_branch": "main",
  "title": "feat(auth): add OAuth login"
}'

通过标准输入添加合并请求评论：

echo "CI passed. Ready for review." | python scripts/gitlab.py mr-comment 42

检查失败的流水线：

python scripts/gitlab.py pipeline-get 12345 --fields id,status,web_url
python scripts/gitlab.py pipeline-jobs 12345 --fields id,name,status,stage
python scripts/gitlab.py job-log 67890

故障排除

症状	原因	解决方法
GITLAB_URL is not set	缺少必需的环境变量	运行脚本前导出 GITLAB_URL
GITLAB_TOKEN is not set for legacy-token mode	显式旧版模式下未设置 PAT	仅在 GITLAB_AUTH_MODE=legacy-token 时导出 PAT
GITLAB_TOKEN must not be set in oauth mode	旧版 PAT 泄漏到了 OAuth 配置中	移除 GITLAB_TOKEN，或显式选择旧版令牌模式
Windows 上无法使用 OAuth 持久化功能	没有受保护的 Windows 配置文件存储后端	使用显式旧版令牌模式，或在 POSIX 环境中运行 OAuth
GITLAB_OAUTH_CLIENT_ID is not set	尚未配置 OAuth 应用	设置公开客户端 ID，然后运行 auth login
回调监听器无法绑定	端口 8766 不可用或未转发	释放该端口，或使用 auth device-login
timed out waiting for the GitLab OAuth token store lock	另一个进程持有配置文件存储锁	等待另一条命令完成，然后重试
GitLab device response has invalid verification_uri	验证 URI 不适合显示，或与 GITLAB_URL 不匹配	确认 GITLAB_URL 与提供设备验证的实例一致
cannot parse git remote URL	项目自动检测失败	显式设置 GITLAB_PROJECT
HTTP 401 或 HTTP 403	凭据无效或没有访问权限	重新登录以使用 OAuth；在显式旧版模式下轮换 PAT
HTTP 404	项目、MR IID、流水线 ID 或作业 ID 错误	验证 GITLAB_PROJECT，并确认数字标识符
expected numeric ID	传递给 ID 参数的值不是数字	使用项目 MR IID 值，以及数字格式的流水线 ID 或作业 ID
启动时出现 python3 is required 或语法错误	解释器不受支持	使用 Python 3.11 或更高版本运行脚本

GitLab 在项目内使用 !42 这类 MR IID。此工具要求提供数字 IID，而非全局合并请求 ID。