关于GitLabAPI的详细使用教程

1 简介

GitLab 作为一个开源、强大的分布式版本控制系统，已经成为互联网公司、软件开发公司的主流版本管理工具。使用过 GitLab 的都知道，想要提交一段代码，可以通过 git push 提交到远程仓库，也可以直接在 GitLab 平台上修改提交。然而上述两种提交方式都是人工提交代码，需要手动登录 GitLab 或者在第一次 commit 的时候提供 GitLab 帐号和密码。那么，假设有这么一个需求场景：我们开发了一个效率平台，可以自动拉分支、自动提交代码到远程仓库。这个需求该如何实现？其实很简单，GitLab 提供了一套完整的 API，让第三方平台可以通过 API 自动创建帐号、自动提交代码、自动拉分支，等等。API 涉及到的功能非常全面，覆盖了分支、tag、代码提交、用户、群组、项目等，基本上人工可以做的所有操作，都可以通过 API 自动实现。

2 API 介绍

GitLab API 的使用可以参考你所使用的 GitLab 服务上的帮助文档。也可以参考 GitLab API 官网文档。所有 API 请求都需要身份验证。您需要 private_token 通过 URL 或标头传递参数。如果作为标头传递，标头名称必须是“PRIVATE-TOKEN”（大写并用破折号代替下划线）。您可以在个人资料中找到或重置您的私人令牌。登录您的 GitLab 账号，在左侧栏中选定【Profile Settings】，再在左侧栏中选定【Account】，如下图所示：

如果未提供或提供无效，private_token 则将返回错误消息，状态码为 401：

{
\”message\”: \”401 Unauthorized\”
}

API 请求应以 API 的参数和 API 的版本为前缀。API 版本在 lib/api.rb 定义，例如，v4 API 的前缀就是/api/v4。有效 API 请求示例：

GET http://gitlab.example.com/api/v4/projects?private_token=<your_access_token>

使用 curl 和通过标头身份验证的有效 API 请求示例：

curl –header \”PRIVATE-TOKEN: <your_access_token>\” \”http://gitlab.example.com/api/v4/projects\”

这两个例子分别列举了 token 作为参数，和作为 Header 的使用方法。在我们的程序中，我们只需要选择一种自己方便的方式就可以了。API 使用 JSON 来序列化数据。您无需在 API URL 的末尾指定.json。

3 API 使用

3.1 获取 Projects 数据

http://gitlab.example.com/api/v4/projects/<project_id>/repository/branches?private_token=<your_access_token>

通过官方文档的说明，如果要获取一个工程的分支数据，除了 private_token 参数必填之外，还需要知道这个工程的 project_id，但从 GitLab 操作界面上并没有工程 id 查看的入口。所以需要获取到所有 projects 的数据，然后得到某个 project 的所有参数数据。把 URL 域名参数和 Token 参数替换成自己的，用 Linux 命令在终端测试获取下数据：

curl –header \”PRIVATE-TOKEN:<your_access_token>\” \”http://gitlab.example.com/api/v4/projects\”

执行之后获取到的数据是默认前20条（默认一个页面20条数据），JSON 数据结构如下，可以看到里面的 id 字段就是请求分支数据需要的 id 参数。

[
{
\”id\”: 1234,
\”description\”: null,
\”name\”: \”Diaspora Client\”,
\”name_with_namespace\”: \”Diaspora / Diaspora Client\”,
\”path\”: \”diaspora-client\”,
\”path_with_namespace\”: \”diaspora/diaspora-client\”,
\”created_at\”: \”2022-09-30T13:46:02Z\”,
\”default_branch\”: \”main\”,
\”tag_list\”: [
\”example\”,
\”disapora client\”
],
\”topics\”: [
\”example\”,
\”disapora client\”
],
\”ssh_url_to_repo\”: \”git@gitlab.example.com:diaspora/diaspora-client.git\”,
\”http_url_to_repo\”: \”https://gitlab.example.com/diaspora/diaspora-client.git\”,
\”web_url\”: \”https://gitlab.example.com/diaspora/diaspora-client\”,
\”readme_url\”: \”https://gitlab.example.com/diaspora/diaspora-client/blob/master/README.md\”,
\”avatar_url\”: \”https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png\”,
\”forks_count\”: 0,
\”star_count\”: 0,
\”last_activity_at\”: \”2022-09-30T13:46:02Z\”,
\”namespace\”: {
\”id\”: 2,
\”name\”: \”Diaspora\”,
\”path\”: \”diaspora\”,
\”kind\”: \”group\”,
\”full_path\”: \”diaspora\”,
\”parent_id\”: null,
\”avatar_url\”: null,
\”web_url\”: \”https://gitlab.example.com/diaspora\”
}
},
{
…
}
]

3.2 获取指定 Project 数据

如果 GitLab 上有几百个工程，总不能把所有的都获取下来再去过滤吧，通过查看 API 文档可以用 search 参数根据 project 名称去搜索想要获取的 project 数据，比如这边要查找 test 项目的数据。示例请求：

curl –header \”PRIVATE-TOKEN: <your_access_token>\” \”https://gitlab.example.com/api/v4/projects?search=test\”

通过上面这条命令就可以获取到项目名包含 test 的前20条数据（官网文档描述默认20，最大100，可通过 per_page 参数设置）。

3.3 获取 branches 数据

通过前面的步骤获取到 test 项目的数据之后，知道这个project的 id 值，就可以接着通过 id 参数来获取这个 project 的所有分支数据。示例请求：

curl –header \”PRIVATE-TOKEN:<your_access_token>\” \”http://gitlab.xxxxxxx.com/api/v4/projects/<project_id>/repository/branches\”

示例响应：

[
{
\”name\”: \”main\”,
\”merged\”: false,
\”protected\”: true,
\”default\”: true,
\”developers_can_push\”: false,
\”developers_can_merge\”: false,
\”can_push\”: true,
\”web_url\”: \”https://gitlab.example.com/my-group/my-project/-/tree/main\”,
\”commit\”: {
\”author_email\”: \”john@example.com\”,
\”author_name\”: \”John Smith\”,
\”authored_date\”: \”2022-06-27T05:51:39-07:00\”,
\”committed_date\”: \”2022-06-28T03:44:20-07:00\”,
\”committer_email\”: \”john@example.com\”,
\”committer_name\”: \”John Smith\”,
\”id\”: \”7b5c3cc8be40ee161ae89a06bba6229da1032a0c\”,
\”short_id\”: \”7b5c3cc\”,
\”title\”: \”add projects API\”,
\”message\”: \”add projects API\”,
\”parent_ids\”: [
\”4ad91d3c1144c406e50c7b33bae684bd6837faf8\”
]
}
},
…
]

3.4 获取指定 branche 数据

上面是获取这个 project 的所有分支数据，如果要获取指定分支的数据：

GET /projects/:id/repository/branches/:branch

比如获取 master 分支的数据，示例请求：

curl –header \”PRIVATE-TOKEN: <your_access_token>\” \”https://gitlab.example.com/api/v4/projects/<project_id>/repository/branches/master\”

示例响应：

{
\”name\”: \”master\”,
\”merged\”: false,
\”protected\”: true,
\”default\”: true,
\”developers_can_push\”: false,
\”developers_can_merge\”: false,
\”can_push\”: true,
\”web_url\”: \”https://gitlab.example.com/my-group/my-project/-/tree/main\”,
\”commit\”: {
\”author_email\”: \”john@example.com\”,
\”author_name\”: \”John Smith\”,
\”authored_date\”: \”2022-06-27T05:51:39-07:00\”,
\”committed_date\”: \”2022-06-28T03:44:20-07:00\”,
\”committer_email\”: \”john@example.com\”,
\”committer_name\”: \”John Smith\”,
\”id\”: \”7b5c3cc8be40ee161ae89a06bba6229da1032a0c\”,
\”short_id\”: \”7b5c3cc\”,
\”title\”: \”add projects API\”,
\”message\”: \”add projects API\”,
\”parent_ids\”: [
\”4ad91d3c1144c406e50c7b33bae684bd6837faf8\”
]
}
}

3.5 获取仓库提交列表

获取项目中的仓库提交列表：

GET /projects/:id/repository/commits

示例请求：

curl –header \”PRIVATE-TOKEN: <your_access_token>\” \”https://gitlab.example.com/api/v4/projects/<project_id>/repository/commits\”

示例响应：

[
{
\”id\”: \”ed899a2f4b50b4370feeea94676502b42383c746\”,
\”short_id\”: \”ed899a2f4b5\”,
\”title\”: \”Replace sanitize with escape once\”,
\”author_name\”: \”Example User\”,
\”author_email\”: \”user@example.com\”,
\”authored_date\”: \”2022-09-20T11:50:22.001+00:00\”,
\”committer_name\”: \”Administrator\”,
\”committer_email\”: \”admin@example.com\”,
\”committed_date\”: \”2022-09-20T11:50:22.001+00:00\”,
\”created_at\”: \”2022-09-20T11:50:22.001+00:00\”,
\”message\”: \”Replace sanitize with escape once\”,
\”parent_ids\”: [
\”6104942438c14ec7bd21c6cd5bd995272b3faff6\”
],
\”web_url\”: \”https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746\”
},
{
\”id\”: \”6104942438c14ec7bd21c6cd5bd995272b3faff6\”,
\”short_id\”: \”6104942438c\”,
\”title\”: \”Sanitize for network graph\”,
\”author_name\”: \”randx\”,
\”author_email\”: \”user@example.com\”,
\”committer_name\”: \”ExampleName\”,
\”committer_email\”: \”user@example.com\”,
\”created_at\”: \”2022-09-20T09:06:12.201+00:00\”,
\”message\”: \”Sanitize for network graph\”,
\”parent_ids\”: [
\”ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba\”
],
\”web_url\”: \”https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746\”
}
]