ubuntu中gitlab API使用教程

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 便于后续增量同步。