Gerrit REST API简单介绍
Gerrit是一款开源免费的代码审查工具，如果其它平台想要获取gerrit数据，比如统计仓库代码提交数据等信息，可以使用Gerrit提供的REST API来获取，本文记录一些我使用到的Gerrit API。
目录
- 准备工作
- gerrit API
- Gerrit REST API使用实例
-
- 获取所有项目
- 获取项目信息
- 获取项目分支
- 提交记录
- Change Messages
- 提交的详细信息
- 获取评审信息
- 读取用户信息
- API数据返回限制
准备工作
Gerrit安装配置方法可参考代码评审平台Gerrit安装配置方法介绍。
REST API官方文档：https://gerrit-documentation.storage.googleapis.com/Documentation/3.8.0/rest-api.html
也可以点击gerrit平台的 DOCUMENTATION -> REST API 查看：
使用REST API读取数据需要用户名和密码，本文以admin用户为例，进入用户设置页面，找到HTTP Credentials，点击Generate new password，生成一个http认证密码。
我的用户名密码为：
admin
b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw
gerrit API
gerrit主要包括以下8类API：
- /access/：访问权限相关API
- /accounts/：账户相关API
- /changes/：更改相关API
- /config/：配置相关API
- /groups/：分组相关API
- /plugins/：插件相关API
- /projects/：仓库相关API
- /Documentation/：文档相关API
下面仅介绍部分我使用到的接口，使用curl命令来测试。
Gerrit REST API使用实例
获取所有项目
/a/projects/
$ curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/projects/
)]}'
{
"All-Projects": {
"id": "All-Projects",
"state": "ACTIVE",
"web_links": [
{
"name": "browse",
"url": "/plugins/gitiles/All-Projects",
"target": "_blank"
}
]
},
"All-Users": {
"id": "All-Users",
"state": "ACTIVE",
"web_links": [
{
"name": "browse",
"url": "/plugins/gitiles/All-Users",
"target": "_blank"
}
]
},
"gerritDemo": {
"id": "gerritDemo",
"state": "ACTIVE",
"web_links": [
{
"name": "browse",
"url": "/plugins/gitiles/gerritDemo",
"target": "_blank"
}
]
}
}
为了防止XSSI(XSSICross Site Script Inclusion)攻击，JSON响应数据前面包含了 )]}' 字符，在后续的数据处理中需要将其删除。
获取项目信息
/a/projects/gerritDemo
$ curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/projects/gerritDemo
)]}'
{
"id": "gerritDemo",
"name": "gerritDemo",
"parent": "All-Projects",
"state": "ACTIVE",
"web_links": [
{
"name": "browse",
"url": "/plugins/gitiles/gerritDemo",
"target": "_blank"
}
],
"labels": {
"Verified": {
"values": {
" 0": "No score",
"-1": "Fails",
"+1": "Verified"
},
"default_value": 0
},
"Code-Review": {
"values": {
" 0": "No score",
"-1": "I would prefer this is not submitted as is",
"-2": "This shall not be submitted",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"default_value": 0
}
}
}
获取项目分支
/a/projects/gerritDemo/branches/
curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/projects/gerritDemo/branches/
)]}'
[
{
"ref": "HEAD",
"revision": "master"
},
{
"web_links": [
{
"name": "browse",
"url": "/plugins/gitiles/gerritDemo/+/refs/meta/config",
"target": "_blank"
}
],
"ref": "refs/meta/config",
"revision": "8c739812c1813c52b47db8cb42aeffdacf84baaf"
},
{
"web_links": [
{
"name": "browse",
"url": "/plugins/gitiles/gerritDemo/+/refs/heads/master",
"target": "_blank"
}
],
"ref": "refs/heads/master",
"revision": "44438ca8f90741ef10e10a6574487975d2f82141"
}
]
提交记录
changes: /a/changes/
过滤条件：project:gerritDemo status:open branch:master
REST API：
curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/changes/?q=status:open+project:gerritDemo+branch:master
返回：
curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/changes/?q=status:open+project:gerritDemo+branch:master
)]}'
[
{
"id": "gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd",
"project": "gerritDemo",
"branch": "master",
"topic": "test",
"attention_set": {
"1000001": {
"account": {
"_account_id": 1000001
},
"last_update": "2023-07-04 13:30:26.000000000",
"reason": " replied on the change" ,
"reason_account": {
"_account_id": 1000000
}
}
},
"removed_from_attention_set": {},
"hashtags": [],
"change_id": "Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd",
"subject": "gerrit提交测试",
"status": "NEW",
"created": "2023-07-03 13:00:34.000000000",
"updated": "2023-07-04 13:32:30.000000000",
"submit_type": "MERGE_IF_NECESSARY",
"insertions": 1,
"deletions": 0,
"total_comment_count": 1,
"unresolved_comment_count": 0,
"has_review_started": true,
"meta_rev_id": "f0c2f1952432d62db1f6b8d23d83e4399facab25",
"_number": 1,
"owner": {
"_account_id": 1000000
},
"requirements": [],
"submit_records": [
{
"rule_name": "gerrit~DefaultSubmitRule",
"status": "NOT_READY",
"labels": [
{
"label": "Code-Review",
"status": "NEED"
},
{
"label": "Verified",
"status": "NEED"
}
]
}
]
}
]
Change Messages
通过change ID读取提交的详细信息：a/changes/gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd/messages，包含评分及评论内容。
$ curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/changes/gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd/messages
)]}'
[
{
"id": "0556a0aff79e94456565d656c7eabf31c5bd07fb",
"tag": "autogenerated:gerrit:newPatchSet",
"author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"real_author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"date": "2023-07-03 13:00:34.000000000",
"message": "Uploaded patch set 1.",
"accounts_in_message": [],
"_revision_number": 1
},
{
"id": "28d364b0bd5018a556b1a0bd41c6fb0dd1d1c739",
"author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"real_author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"date": "2023-07-03 13:42:19.000000000",
"message": "Patch Set 1: Verified+1 Code-Review+1\n\n(1 comment)",
"accounts_in_message": [],
"_revision_number": 1
},
................................
]
提交的详细信息
a/changes/UGW_main~dev_ugw6.0_main_for_AX2Pro~Ifc3ec88e7f6648a834a743c465dd7cce1c268789/detail：某次提交的详细信息，比messages更详细，包括评审人、评审等信息。
$ curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/changes/gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd/detail
)]}'
{
"id": "gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd",
"project": "gerritDemo",
"branch": "master",
"topic": "test",
"attention_set": {
"1000001": {
"account": {
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
},
"last_update": "2023-07-04 13:30:26.000000000",
"reason": " replied on the change" ,
"reason_account": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
}
}
},
"removed_from_attention_set": {},
"hashtags": [],
"change_id": "Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd",
"subject": "gerrit提交测试",
"status": "NEW",
"created": "2023-07-03 13:00:34.000000000",
"updated": "2023-07-04 13:32:30.000000000",
"submit_type": "MERGE_IF_NECESSARY",
"insertions": 1,
"deletions": 0,
"total_comment_count": 1,
"unresolved_comment_count": 0,
"has_review_started": true,
"meta_rev_id": "f0c2f1952432d62db1f6b8d23d83e4399facab25",
"_number": 1,
"owner": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"labels": {
"Code-Review": {
"all": [
{
"value": 0,
"permitted_voting_range": {
"min": -1,
"max": 1
},
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
},
{
"value": 0,
"date": "2023-07-04 13:30:26.000000000",
"permitted_voting_range": {
"min": -2,
"max": 2
},
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
}
],
"values": {
"-2": "This shall not be submitted",
"-1": "I would prefer this is not submitted as is",
" 0": "No score",
"+1": "Looks good to me, but someone else must approve",
"+2": "Looks good to me, approved"
},
"description": "",
"default_value": 0
},
"Verified": {
"all": [
{
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
},
{
"value": 0,
"date": "2023-07-04 13:30:26.000000000",
"permitted_voting_range": {
"min": -1,
"max": 1
},
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
}
],
"values": {
"-1": "Fails",
" 0": "No score",
"+1": "Verified"
},
"description": "",
"default_value": 0
}
},
"permitted_labels": {
"Code-Review": [
"-2",
"-1",
" 0",
"+1",
"+2"
],
"Verified": [
"-1",
" 0",
"+1"
]
},
"removable_reviewers": [
{
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
},
{
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
}
],
"reviewers": {
"REVIEWER": [
{
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
{
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
}
]
},
"pending_reviewers": {},
"reviewer_updates": [
{
"updated": "2023-07-04 13:30:26.000000000",
"updated_by": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"reviewer": {
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
},
"state": "REVIEWER"
}
],
"messages": [
{
"id": "0556a0aff79e94456565d656c7eabf31c5bd07fb",
"tag": "autogenerated:gerrit:newPatchSet",
"author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"real_author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"date": "2023-07-03 13:00:34.000000000",
"message": "Uploaded patch set 1.",
"accounts_in_message": [],
"_revision_number": 1
},
{
"id": "28d364b0bd5018a556b1a0bd41c6fb0dd1d1c739",
"author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"real_author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"date": "2023-07-03 13:42:19.000000000",
"message": "Patch Set 1: Verified+1 Code-Review+1\n\n(1 comment)",
"accounts_in_message": [],
"_revision_number": 1
},
{
"id": "8a4eb8d2a7fd3bc7481e6365b3afff3b7d2f54f7",
"author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"real_author": {
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
},
"date": "2023-07-03 13:42:47.000000000",
"message": "Patch Set 1: Code-Review+2",
"accounts_in_message": [],
"_revision_number": 1
},
..........................
],
"requirements": [],
"submit_records": [
{
"rule_name": "gerrit~DefaultSubmitRule",
"status": "NOT_READY",
"labels": [
{
"label": "Code-Review",
"status": "NEED"
},
{
"label": "Verified",
"status": "NEED"
}
]
}
]
}
获取评审信息
评审人：/a/changes/gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd/reviewers
$ curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/changes/gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd/reviewers
)]}'
[
{
"approvals": {
"Code-Review": " 0"
},
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
},
{
"approvals": {
"Code-Review": " 0",
"Verified": " 0"
},
"_account_id": 1000000,
"name": "admin",
"email": "[email protected]",
"username": "admin"
}
]
$ curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/a/changes/gerritDemo~master~Ia461fa2b266a749a8e195bb668938cc5c4f8a2dd/reviewers/[email protected]
)]}'
[
{
"approvals": {
"Code-Review": " 0"
},
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
}
]
读取用户信息
/accounts/1000001
$curl --user admin:b0JoSt8KQHm5OhHhBsH+HN+GNVK9OPXrUzjGCXbxuw http://172.23.23.31:8081/accounts/1000001
)]}'
{
"_account_id": 1000001,
"name": "gerrit",
"email": "[email protected]",
"username": "gerrit"
}
API数据返回限制
Gerrit REST API限制了一次请求最多返回500条记录，如果当前请求接口数据大于500条，在最后一条记录会有一个名称为_more_changes 的字段，值为true 。
...............
{
"id": "demo~master~I09c8041b5867d5b33170316e2abc34b79bbb8501",
"project": "demo",
"branch": "master",
"change_id": "I09c8041b5867d5b33170316e2abc34b79bbb8501",
"subject": "Another change",
"status": "NEW",
"created": "2012-07-17 07:18:30.884000000",
"updated": "2012-07-17 07:18:30.885000000",
"mergeable": true,
"insertions": 12,
"deletions": 18,
"_number": 1757,
"owner": {
"name": "John Doe"
},
"_more_changes": true
}
]
可以使用 S 参数来读取更多记录：
http://172.16.30.72:8080/a/changes/?q=project:UGW_main+branch:dev_ugw6.0_main&S=0
http://172.16.30.72:8080/a/changes/?q=project:UGW_main+branch:dev_ugw6.0_main&S=500
http://172.16.30.72:8080/a/changes/?q=project:UGW_main+branch:dev_ugw6.0_main&S=1000
参考文档：
- 官网：https://www.gerritcodereview.com/
- 接口说明文档：https://gerrit-documentation.storage.googleapis.com/Documentation/3.8.0/rest-api.html
相关阅读：
- 代码评审平台Gerrit安装配置方法介绍