角色权限等级表

角色	accessLevel值
Owner	50
Maintainer	40
Developer	30
Reporter	20
Guest	10
No one	0

gitlab MR状态

1. open
2. merged
3. closed

设置保护分支

仅 Maintainer 及以上级别可操作

• 在 gitlab 里 Settings > Repository > Protected branches.
• 允许合并MR、推送代码等级权限分别设置为40、40/0

相关接口：

假设私有化部署的地址为：gitlab.local.com

1. 所有请求头部Headers需添加access token，key-value字段如下： Authorization: Bearer ${access_token}

2. 根据项目名称匹配查询项目 id 即 projectId

   • 请求方法：get
   • url：http://gitlab.local.com/api/v4/search?scope=projects&search=${projectName}
   • 参数：
     • projectName：项目名称
   • 注：
     • 是模糊匹配查询，可能返回多个项目，需取项目地址比较匹配筛选出目标

3. 查询所有项目成员

   • 请求方法：get
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/members
   • 参数：
     • projectId：项目id
   • 注：
     • 可获取成员（不含Owner）等级权限，筛选出管理员

4. 设置保护分支

   • 请求方法：post
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/protected_branches?name=${branchName}&push_access_level=${accessLevel}&merge_access_level=${accessLevel}
   • 参数：
     • projectId：项目id
     • branchName：分支名，需转译特殊字符
     • accessLevel：权限值，参考“角色权限等级表”
   • 响应码：
     • 201：成功
     • 409：已是保护分支

5. 解除保护分支

   • 请求方法：delete
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/protected_branches/${branchName}
   • 参数：
     • projectId：项目id
     • branchName：分支名，需转译特殊字符
   • 响应码：
     • 204：成功

6. 发起MR

   • 请求方法：post
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/merge_requests?source_branch=${sourceBranch}&target_branch=${targetBranch}&title=${title}
   • 参数：
     • projectId：项目id
     • sourceBranch：MR源分支
     • targetBranch：MR目标分支
     • title：MR标题文案，需转译特殊字符
     • description：MR描述文案，需转译特殊字符
     • remove_source_branch：是否删除源分支，默认no
   • 响应码：
     • 201：成功
     • 409：已存在源分支至目标分支的MR（open状态）
   • 响应字段：
     • iid：MR的iid，数字从1开始每每+1递增
     • state：状态，MR状态，发起后为opened
     • web_url：发起的MR的详情地址，可生成如下地址使用
       • CR：${web_url}/commits
       • conflict：${web_url}/conflicts
     • has_conflicts：MR有冲突、MR中没有代码提交/变更时值为true
     • changes_count：变更的文件总数量，无则为null
     • diff_refs：可通过比较base_sha和head_sha判断是否有代码提交/变更
       • base_sha：源分支最近一次提交sha
       • head_sha：源分支与目标分支最近公共节点提交的sha
       • start_sha：目标分支最近一次提交sha

7. 合并MR

   • 请求方法：put
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/merge_requests/${MRIid}/merge
   • 参数：
     • projectId：项目id
     • MRIid：MR的iid，从发起MR响应中获取
   • 响应码：
     • 200：成功
     • 405：MR中没有代码提交/变更、MR已关闭等原因，无法合并
     • 406：有冲突，无法合并

8. 关闭MR

   • 请求方法：put
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/merge_requests/${MRIid}?state_event=close
   • 参数：
     • projectId：项目id
     • MRIid：MR的iid，从发起MR响应中获取
   • 响应码：
     • 200：成功
   • 注：
     • 用于开发者取消订单、管理员打回订单时取消MR

9. 查询一个MR

   • 请求方法：get
   • url：http://gitlab.local.com/api/v4/projects/${projectId}/merge_requests/${MRIid}
   • 参数：
     • projectId：项目id
     • MRIid：MR的iid，从发起MR响应中获取
   • 响应码：
     • 200：成功

10. 创建webhook

    • 请求方法：post
    • url：http://gitlab.local.com/api/v4/projects/${projectId}/hooks?url=${url}&merge_requests_events=true&push_events=false
    • 参数：
      • projectId：项目id
      • url：webhook回调通知的链接
      • merge_requests_events：是否监听MR创建等事件
      • push_events：是否监听代码推送事件
    • 响应码：
      • 201：成功

11. 删除webhook

    • 请求方法：delete
    • url：http://gitlab.local.com/api/v4/projects/${projectId}/hooks/${hookId}
    • 参数：
      • projectId：项目id
      • hookId：webhook的id，在创建webhook响应中获取
    • 响应码：
      • 204：成功
      • 404：webhook不存在

12. webhook回调信息

    • 请求方法：post
    • req.body。只需监听event_type: merge_request且action: merge/close的推送

    {
    	"event_type": "merge_request",
    	"project": {
    		"id": "",
    		"web_url": ""
    	},
    	"object_attributes": {
    		"iid": "",
    		"action": "open/merge/close", // 对应操作依次为创建/合并/关闭MR
    		"state": "opened/merged/closed",
    		"source_branch": "",
    		"target_branch": ""
    	}
    }
    

    • req.headers

    {
    	"content-type": "application/json",
    	"x-gitlab-event": "Merge Request Hook"
    }
    

参考

• Gitlab API (opens new window)
• API Resources (opens new window)
• Protected branches API (opens new window)