GitLab的API接口如何使用

GitLab API 使用指南

准备访问令牌：登录 GitLab，进入头像 → Edit profile → Access Tokens，创建Personal Access Token（选择所需权限，如 api、read_user、read_repository 等），妥善保存生成的令牌。
基础请求地址：所有接口均以**/api/v4**为前缀，例如：https://gitlab.example.com/api/v4/projects。
身份认证方式：
- 使用Personal/Project Access Token：在请求头中使用Private-Token: 或查询参数private_token=。
- 使用OAuth2 Token：在请求头中使用Authorization: Bearer 或查询参数access_token=。
常见返回与分页：接口默认返回JSON；列表接口默认20条/页，可通过page与per_page控制分页（如：?page=2&per_page=100）。

认证方式	适用场景	请求示例	备注
Personal/Project Access Token	脚本、服务账户、CI	curl 头：Private-Token: ；或 ?private_token=	也可用Authorization: Bearer （OAuth 兼容）
OAuth2 Token	第三方应用、Web 前端	curl 头：Authorization: Bearer ；或 ?access_token=	推荐使用Authorization Code + PKCE；Implicit 可在前端使用
GitLab CI/CD Job Token	CI 作业中调用受支持端点	在 CI 环境使用 CI_JOB_TOKEN	仅限部分端点，能力受限
Session Cookie	已登录浏览器会话	浏览器自动携带	不适用于服务端脚本
Impersonation Token / Sudo	管理员代表用户操作	需管理员权限	谨慎使用，遵循最小权限原则

获取项目列表（curl）
curl --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects?page=1&per_page=100”
获取文件原始内容（curl）
curl --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/repository/files/app%2Fmodels%2Fkey.rb/raw?ref=main”
使用 python-gitlab 列出项目
pip install --upgrade python-gitlab
python
import gitlab
gl = gitlab.Gitlab(‘https://gitlab.example.com’, private_token=‘’)
projects = gl.projects.list(all=True)
for p in projects: print(p.id, p.name)
触发流水线中的 Job（curl）
curl --request POST “https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/jobs/<JOB_ID>/play” --header “PRIVATE-TOKEN: ”
使用 OAuth2 令牌访问 API（curl）
curl --header “Authorization: Bearer <OAUTH_TOKEN>” “https://gitlab.example.com/api/v4/user”

权限最小化：仅勾选所需的Scopes（如只读选read_api/read_repository，写操作再选api）。
安全存储：令牌不要硬编码或提交到代码库，使用环境变量/密钥管理；CI 中优先用CI_JOB_TOKEN或受管的项目/个人令牌。
分页处理：列表接口务必处理page/per_page与Link响应头，避免漏数据。
分支/Tag 名称含特殊字符时需URL 编码（如将**/编码为%2F**）。
错误排查：遇到401 Unauthorized检查令牌是否有效、是否过期、是否具备对应Scope；必要时用**/api/v4/user**验证令牌身份。