Ubuntu 中使用 GitLab API 的完整教程
一 环境准备与令牌创建
- 安装常用工具（Ubuntu）：sudo apt update && sudo apt install -y curl jq python3 python3-pip git
- 创建访问令牌（PAT）：登录 GitLab → 右上角头像 → Settings → Access Tokens → 新建 Personal Access Token，勾选所需权限（如 api、read_repository、write_repository 等），妥善保存生成的令牌（只显示一次）。如使用自建实例，请确认实例地址与网络可达。
二 认证方式与请求要点
- 支持的认证方式：
- OAuth2 Token：在 URL 参数 access_token 或请求头 Authorization: Bearer 中使用。
- Personal/Project Access Token：在 URL 参数 private_token 或请求头 PRIVATE-TOKEN: 中使用，也兼容 Authorization: Bearer 。
- 其他：Session Cookie、GitLab CI/CD Job Token（限特定端点）、管理员可用的 Impersonation Token 与 Sudo。
- 常见要点：
- API 基础路径为 /api/v4。
- 分页参数：page、per_page（如 ?per_page=100）。
- 多数接口需认证，失败返回 401 Unauthorized。
三 常用操作速查
- 获取项目列表（支持分页）
- curl --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects?per_page=100&page=1”
- 获取项目文件原始内容（需 URL 编码文件路径）
- curl --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=main”
- 通过提交接口创建/更新文件（Commit）
- curl --request POST --header “PRIVATE-TOKEN: ” --header “Content-Type: application/json”
–data ‘{ “branch”: “main”, “commit_message”: “add file”, “actions”: [{ “action”: “create”, “file_path”: “hello.txt”, “content”: “Hello GitLab” }] }’
“https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/repository/commits”
- 批量镜像克隆所有仓库（Shell + jq）
- curl -s --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects?per_page=1000” |
jq -r ‘.[].ssh_url_to_repo’ | while read repo; do git clone --mirror “$repo”; done
- 触发流水线 Job 执行
- curl --request POST --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/jobs/<JOB_ID>/play”
- 合并 Merge Request
- curl --request PUT --header “PRIVATE-TOKEN: ” “https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/merge_requests/<MR_IID>/merge”
四 Python 示例
- 使用 requests 提交文件
- pip install requests
- 代码示例：
- import requests
GITLAB_URL = “https://gitlab.example.com/api/v4”
PROJECT_ID = 123
TOKEN = “<YOUR_TOKEN>”
url = f"{GITLAB_URL}/projects/{PROJECT_ID}/repository/commits"
headers = {“PRIVATE-TOKEN”: TOKEN}
data = {
“branch”: “main”,
“commit_message”: “add file via API”,
“actions”: [{
“action”: “create”,
“file_path”: “hello.txt”,
“content”: “Hello, GitLab API”
}]
}
r = requests.post(url, headers=headers, json=data)
print(r.status_code, r.json())
- 使用 python-gitlab（更贴近面向对象的操作）
- pip install python-gitlab
- 代码示例：
- import gitlab
gl = gitlab.Gitlab(“https://gitlab.example.com”, private_token=“<YOUR_TOKEN>”)
project = gl.projects.get(123)
project.branches.create({“branch”: “feature/x”, “ref”: “main”})
mr = project.mergerequests.create({
“source_branch”: “feature/x”,
“target_branch”: “main”,
“title”: “Add feature x”
})
mr.merge()
五 常见问题与排查
- 401 Unauthorized：检查令牌是否有效、是否勾选了对应 Scopes，以及请求头是否为 PRIVATE-TOKEN 或 Authorization: Bearer。
- 404 Not Found：确认 PROJECT_ID 正确、分支/文件路径存在，文件路径需 URL 编码（如空格→%20）。
- 分页数据不全：使用 page 与 per_page 遍历，或增加 per_page（上限视实例配置）。
- 触发 Job 失败：确认 JOB_ID 属于该项目且状态允许执行（如非已取消/非运行中）。
- 批量克隆慢或中断：建议增加错误重试、限制并发，或使用 –mirror 便于后续增量同步。
