Z Tag
管理组织服务与凭证配置

GitLab

配置 GitLab PAT、实例地址与 API 访问范围。

适用于组织 Owner / Admin;成员的个人连接器同样适用

在连接器的 访问内容 → 添加访问 中,从 服务预设 选择 GitLab,使用 推荐配置。

获取与填写凭证

  1. 登录目标 GitLab 实例,在个人设置的 Access tokens 中创建 Personal access token。
  2. 选择到期时间与所需 scope。只读 API 可使用 read_api;需要写入时选择 api。read_repository 主要用于 Git 仓库读取,不能替代所有 API 权限。
  3. 复制 Token,填入 PAT。推荐配置会自动把它放进 private-token 请求头。

官方说明:Personal access tokens。

服务地址

默认地址是 https://gitlab.com。自建实例填写 https://<实例域名>,非标准 HTTPS 端口也可填写。GitLab 部署在子路径下时,改用 自定义 并填写实际 API 路径。

请求头

推荐配置固定使用 private-token 请求头,只需填写值。切换到 自定义 后,在 自定义请求头 中填写名称和值:名称可以从提示的常见名称里选择,也可以自己输入。替换凭证时只需重新填写值,请求头名称保持不变。

API 访问范围

推荐配置只允许访问 /api/v4 下的 REST API,能访问哪些项目由 Token 本身的权限决定。要进一步限制路径或请求方法,或放行 /api/graphql 等其他路径,切换到 自定义,在 访问目标 的 协议、路径和内网设置 里填写。

这份凭证只用于调用 GitLab API,不能用来拉取或推送代码;拉取、推送代码和 LFS 文件请在连接器的 访问内容 分区中配置,参见 Git 仓库。

ZAI 可以用预装的 GitLab CLI(glab)或 HTTP 请求,通过这份凭证调用 GitLab.com 或自建实例的 API;glab 中依赖 GraphQL 的命令,要先按上面的方法放行 /api/graphql 才能使用。

验证

保存后请 ZAI 读取一次当前用户(GET /api/v4/user,Token 有 read_api 或 api scope 即可),确认凭证可用,且返回的是预期账号。GitLab 部署在子路径下时,请求路径要带上子路径,例如 /<子路径>/api/v4/user。其余排查见验证与排错。

本页目录