合并请求 | 帮助文档 - 工蜂合作伙伴版

# 合并请求

如果使用 project_full_path，确保 project_full_path 编码过，例子：/api/v3/projects/tencent/code--> /api/v3/projects/tencent%2Fcode (/ 编码 %2F)

MR 状态值（state）说明：
opened：MR 当前是打开的
closed：MR 已经被人为关闭
merged：MR 的代码内容已经正常合并
reopened：MR 从 closed 重新被打开
locked：MR 合并中，锁定

# 新增合并请求

在项目中创建一个合并请求

审批人规则：-1：所有评审人通过，1：单评审通过，2+：多评审通过 (用>=2 的数字代表需要几位必要评审人通过)。
必要审批人规则：-1：所有必要评审人通过，1：单必要评审通过，2+：多必要评审通过 (用>=2 的数字代表需要几位必要评审人通过)，0: 不需要必要评审人即可通过。

POST /api/v3/projects/:id/merge_requests

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
source_branch	string	源分支
target_branch	string	目标分支
title	string	合并请求的标题
assignee_id	integer（可选）	负责人 id
description	string（可选）	合并请求的描述
target_project_id	integer（可选）	目标项目的 id
labels	string（可选）	合并请求的标签，多个请用英文逗号分隔
reviewers	string（可选）	评审人 id (只能是 id。多个评审人请用英文逗号分隔)
necessary_reviewers	string（可选）	必要评审人 id (只能是 id。多个评审人请用英文逗号分隔)
approver_rule	integer（可选）	评审人规则
necessary_approver_rule	integer（可选）	必要评审人规则
selected_files	array of string (可选)	传重点文件路径数组，参数为空时默认所有都是重点文件

返回值：

{
    "id": 25563,
    "title": "merge request title",
    "target_project_id": 12321,
    "target_branch": "master",
    "source_project_id": 12321,
    "source_branch": "branch1",
    "state": "opened",
    "iid": 5,
    "description": "desc",
    "created_at": "2015-03-21T06:26:38+0000",
    "updated_at": "2015-03-21T06:26:38+0000",
    "resolved_at": null,
    "labels": [],
    "assignee": null,
    "author": {
        "id": 1055,
        "name": "jim",
        "username": "jim",
        "state": "active",
        "avatar_url": null
    },
    "milestone": {
        "id": 1103,
        "project_id": 12321,
        "title": "milestone1",
        "state": "active",
        "iid": 1,
        "due_date": null,
        "created_at": "2012-10-15T06:02:45+0000",
        "updated_at": "2012-10-15T06:02:45+0000",
        "description": "milestone1"
    },
    "project_id": 29723,
    "work_in_progress": false,
    "upvotes": 0,
    "downvotes": 0,
    "has_conflicts": false,
    "resolve_conflicts_url": null
}

# 合并合并请求

在项目内合并某个指定的合并请求，目前支持三种合并类型Create a merge commit(merge)、Squash and merge(squash)、Rebase and merge(rebase)。

PUT /api/v3/projects/:id/merge_request/:merge_request_id/merge

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id
merge_type	string(可选)	合并的类型，默认值是 merge，可选的值包括 (merge/squash/rebase)
merge_commit_message	string（可选）	合并合并请求的描述消息

返回值：

{
    "labels": [],
    "id": 13645071,
    "title": "merge request title",
    "target_project_id": 1212143,
    "target_branch": "master",
    "source_project_id": 1212143,
    "source_branch": "branch1",
    "state": "merged",
    "merge_status": "can_be_merged",
    "commit_check_state": null,
    "commit_check_block": false,
    "iid": 1,
    "description": "desc",
    "created_at": "2023-12-25T06:13:12+0000",
    "updated_at": "2023-12-25T06:19:11+0000",
    "resolved_at": "2023-12-25T06:19:11+0000",
    "merge_type": "Merge",
    "assignee": null,
    "author": {
        "id": 305890,
        "username": "git-user1",
        "web_url": "https://git.tencent.com/u/git—user1",
        "name": "git-user1",
        "state": "active",
        "avatar_url": "GONGFENG HOST@@/uploads/user/avatar/305890/thumb_0-0-240-240_70a761e5b96049668a7bebd2c07df92c.jpeg"
    },
    "merge_commit_sha": "2f5eae63cfe7539a30f5e394b540ef777b343444",
    "milestone": null,
    "necessary_reviewers": null,
    "suggestion_reviewers": null,
    "work_in_progress": false,
    "upvotes": 0,
    "downvotes": 0,
    "project_id": 1212143
}

# 获取合并请求中的提交

获取项目中某个指定合并请求的提交列表（最多返回 120 个提交）

GET /api/v3/projects/:id/merge_request/:merge_request_id/commits

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	string	合并请求的 ID
page	integer(可选）	分页（默认值：`1`）
per_page	integer(可选）	每页的项目数， (default: `120`, max: `120`)

返回值：


[
    {
        "id": "34a677f562eaaeb8a54afe08d65b74165604adda",
        "short_id": "34a677f5",
        "title": null,
        "author_name": "git_user1",
        "author_email": "git_user1@tencent.com",
        "created_at": "2015-10-17T07:24:07+0000",
        "message": "fix"
    },
    {
        "id": "1dfbb3a9d7fcb9a9709f21712f501e9d5835137a",
        "short_id": "1dfbb3a9",
        "title": "branch",
        "author_name": "git_user1",
        "author_email": "git_user1@tencent.com",
        "created_at": "2015-10-18T08:39:49+0000",
        "message": "branch"
    }
]

# 添加合并请求的评论

在指定的合并请求下添加评论

POST /api/v3/projects/:id/merge_request/:merge_request_id/comments

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id
note	string	评论内容

返回值：

{
    "id": 3564,
    "parent_id": null,
    "body": "note test",
    "attachment": null,
    "author": {
        "id": 11323,
        "username": "git—user1",
        "web_url": "https://git.tencent.com/u/git—user1",
        "name": "git—user1",
        "state": "active",
        "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
    },
    "created_at": "2013-03-21T07:38:27+0000",
    "system": false,
    "risk": 0,
    "resolve_state": 0,
    "line_code": null,
    "commit_id": null,
    "file_path": null,
    "note_position": null
}

# 获取合并请求评论列表

获取项目内某个指定合并请求的评论列表

GET /api/v3/projects/:id/merge_request/:merge_request_id/comments

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id
page	integer	分页（默认值：`1`）
per_page	integer	默认页面大小（默认值： `20`，最大值： `100`）

返回值：

[
    {
        "id": 2356,
        "parent_id": null,
        "body": "note test",
        "attachment": null,
        "author": {
            "id": 11323,
            "username": "git—user1",
            "web_url": "https://git.tencent.com/u/git—user1",
            "name": "git—user1",
            "state": "active",
            "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
    },
        "created_at": "2013-01-31T06:12:09+0000",
        "system": false,
         "risk": 0,
        "resolve_state": 0,
        "line_code": "8ec9a00bfd09b3190ac6b22251dbb1aa95a0579d_2_1",
        "commit_id": null,
        "file_path": "README.md",
        "note_position": {
            "origin_position": {
                "note_id": 1994887,
                "left_line_num": null,
                "right_line_num": 1,
                "base_commit_sha": "4005aa9208694462804d22ed314127afda8e3098",
                "start_commit_sha": "71a4e53e47ad4b6b20e6ddb13e493c669c4d631d",
                "head_commit_sha": "98886e92114d016d01c8d2b669b6affbaae8d1f1",
                "new_path": "README.md",
                "old_path": "README.md"
            },
            "outdate_position": null,
            "latest_position": {
                "note_id": 1994887,
                "left_line_num": null,
                "right_line_num": 1,
                "base_commit_sha": "4005aa9208694462804d22ed314127afda8e3098",
                "start_commit_sha": "71a4e53e47ad4b6b20e6ddb13e493c669c4d631d",
                "head_commit_sha": "98886e92114d016d01c8d2b669b6affbaae8d1f1",
                "new_path": "README.md",
                "old_path": "README.md"
            }
        },
        "comments": []
    }
]

# 更新合并请求

在项目内更新某个指定的合并请求

PUT /api/v3/projects/:id/merge_request/:merge_request_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id
target_branch	string（可选）	目标分支
assignee_id	integer（可选）	负责人 id
title	string（可选）	合并请求的标题
state_event	string（可选）	新的状态，可选值：（close 或 reopen）
description	string（可选）	合并请求的描述
labels	string（可选）	合并请求的标签，多个请用英文逗号分隔

返回值：

{
    "id": 38546,
    "title": "merge request update",
    "target_project_id": 12321,
    "target_branch": "master",
    "source_project_id": 12321,
    "source_branch": "branch1",
    "state": "closed",
    "iid": 9,
    "description": "desc",
    "created_at": "2013-01-30T08:24:46+0000",
    "updated_at": "2013-03-21T08:34:44+0000",
    "labels": [],
    "assignee": null,
    "author": {
        "id": 11323,
        "name": "git_user1",
        "username": "git_user1",
        "state": "active",
        "avatar_url": null
    },
    "milestone": {
        "id": 1103,
        "project_id": 12321,
        "title": "milestone1",
        "state": "active",
        "iid": 1,
        "due_date": null,
        "created_at": "2012-11-13T08:06:31+0000",
        "updated_at": "2012-11-13T08:06:31+0000",
        "description": "milestone1"
    },
    "project_id": 29723,
    "work_in_progress": false,
    "upvotes": 0,
    "downvotes": 0
}

# 获取合并请求列表

查询项目的合并请求列表

GET /api/v3/projects/:id/merge_requests
GET /api/v3/projects/:id/merge_requests?state=opened
GET /api/v3/projects/:id/merge_requests?iid=42

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
iid	integer（可选）	项目里面的合并请求 id 编号
iids[]	array of integer（可选）	合并请求的编号，使用时需转义. 如:iids[]=1&iids[]=2 --> iids%5B%5D=1&iids%5B%5D=2
state	string（可选）	合并请求状态，可选值：`merged`, `opened`, `reopened` 或 `closed`，不填写返回所有的合并请求
source_branch	string (可选)	源分支名，指定之后返回列表会根据此源分支名称进行过滤
target_branch	string (可选)	目标分支名，指定之后返回列表会根据此目标分支名称进行过滤
order_by	string（可选）	排序字段，允许按 `created_at`, `updated_at` `resolve_at`排序（默认 `created_at`）
sort	string（可选）	排序方式，允许 `asc` or `desc`（默认 `desc`）
page	integer	分页（默认值：`1`，最大值： `100`）
per_page	integer	默认页面大小（默认值： `20`，最大值： `100`）
created_after	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之后创建的 MR；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
created_before	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之前创建的 MR；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
updated_after	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之后更新的 MR；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
updated_before	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之前更新的 MR；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）

返回值：

[
    {
        "id": 2556,
        "title": "merge request title",
        "target_project_id": 12321,
        "target_branch": "master",
        "source_project_id": 12321,
        "source_branch": "branch1",
        "state": "opened",
        "iid": 9,
        "description": "desc",
        "created_at": "2013-01-19T07:02:50+0000",
        "updated_at": "2013-01-19T07:02:50+0000",
        "resolved_at": null,
        "assignee": {
            "id": 333,
            "username": "git_user2",
            "web_url": "https://git.tencent.com/u/git_user2",
            "name": "git_user2",
            "state": "active",
            "avatar_url": null
        },
        "author": {
            "id": 11323,
            "username": "git_user1",
            "web_url": "https://git.tencent.com/u/git_user1",
            "name": "git_user1",
            "state": "active",
            "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
        },
        "milestone": null,
        "necessary_reviewers": [{
            "id": 11323,
            "username": "git_user1",
            "web_url": "git.tencent.com/u/git_user1",
            "name": "git_user1",
            "state": "active",
            "avatar_url": "git.tencent.com/assets/images/avatar/no_user_avatar.png",
            "type": "necessary",
            "review_state": "approved",
            "created_at": "2019-07-29T09:37:33+0000",
            "updated_at": "2019-07-29T09:57:43+0000"
        }],
        "suggestion_reviewers": [{
            "id": 11323,
            "username": "git_user1",
            "web_url": "git.tencent.com/u/git_user1",
            "name": "git_user1",
            "state": "active",
            "avatar_url": "git.tencent.com/assets/images/avatar/no_user_avatar.png",
            "type": "suggestion",
            "review_state": "approved",
            "created_at": "2019-07-29T09:37:33+0000",
            "updated_at": "2019-07-29T09:57:43+0000"
        }],
        "project_id": 4559,
        "work_in_progress": false,
        "upvotes": 0,
        "downvotes": 0
    },
    {
        "id": 2535,
        "title": "merge request title",
        "target_project_id": 7,
        "target_branch": "master",
        "source_project_id": 7,
        "source_branch": "branch1",
        "state": "opened",
        "iid": 10,
        "description": "desc",
        "created_at": "2013-01-30T08:24:46+0000",
        "updated_at": "2013-03-21T06:04:50+0000",
        "resolved_at": null,
        "assignee": null,
        "author": {
            "id": 11323,
            "username": "git_user1",
            "web_url": "https://git.tencent.com/u/git_user1",
            "name": "git_user1",
            "state": "active",
            "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
        },
        "milestone": null,
        "project_id": 4559,
        "work_in_progress": false,
        "upvotes": 0,
        "downvotes": 0
    }
]

# 查询合并请求的代码变更

显示某个指定合并请求的详情，包含的文件及修改

GET /api/v3/projects/:id/merge_request/:merge_request_id/changes

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id

返回值：

{
    "id": 26534,
    "title": "merge request title",
    "target_project_id": 12321,
    "target_branch": "master",
    "source_project_id": 12321,
    "source_branch": "branch1",
    "state": "opened",
    "iid": 11323,
    "description": "desc",
    "created_at": "2013-03-21T06:26:38+0000",
    "updated_at": "2013-03-21T06:26:38+0000",
    "resolved_at": null,
    "labels": [],
    "assignee": null,
    "author": {
            "id": 11323,
            "username": "git—user1",
            "web_url": "https://git.tencent.com/u/git—user1",
            "name": "git—user1",
            "state": "active",
            "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
    },
    "milestone": {
        "id": 1103,
        "project_id": 4559,
        "title": "milestone1",
        "state": "active",
        "iid": 1,
        "due_date": null,
        "created_at": "2012-11-15T08:02:31+0000",
        "updated_at": "2012-11-15T08:02:31+0000",
        "description": "milestone1"
    },
    "files": [
        {
            "old_path": "/dev/null",
            "new_path": "test",
            "a_mode": 0,
            "b_mode": 33188,
            "diff": "@@ -0,0 +1 @@\n+hello, world\n\\ No newline at end of file\n",
            "new_file": true,
            "renamed_file": false,
            "deleted_file": false,
            "is_too_large": false,
            "is_collapse": false,
            "additions":1,
            "deletions":2
        }
    ],
    "project_id": 4559,
    "work_in_progress": false,
    "upvotes": 0,
    "downvotes": 0
}

# 查询项目合并请求 (根据 id)

查询项目下某个指定合并请求

GET /api/v3/projects/:id/merge_request/:merge_request_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id

返回值：

{
    "id": 235,
    "title": "merge request title",
    "target_project_id": 12321,
    "target_branch": "master",
    "source_project_id": 12321,
    "source_branch": "branch1",
    "state": "opened",
    "iid": 9,
    "description": "desc",
    "created_at": "2013-01-30T08:24:46+0000",
    "updated_at": "2013-03-21T08:34:44+0000",
    "resolved_at": null,
    "labels": [],
    "assignee": null,
    "author": {
            "id": 11323,
            "username": "git—user1",
            "web_url": "https://git.tencent.com/u/git—user1",
            "name": "git—user1",
            "state": "active",
            "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
    },
    "milestone": null,
    "project_id": 45595,
    "work_in_progress": false,
    "upvotes": 0,
    "downvotes": 0
}

# 查询项目合并请求 (根据 iid)

查询项目下某个指定合并请求

GET /api/v3/projects/:id/merge_request/iid/:merge_request_iid

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_iid	integer	合并请求在项目中的编号 iid

返回值：

{
    "id": 235,
    "title": "merge request title",
    "target_project_id": 12321,
    "target_branch": "master",
    "source_project_id": 12321,
    "source_branch": "branch1",
    "state": "opened",
    "iid": 9,
    "description": "desc",
    "created_at": "2013-01-30T08:24:46+0000",
    "updated_at": "2013-03-21T08:34:44+0000",
    "resolved_at": null,
    "labels": [],
    "assignee": null,
    "author": {
            "id": 11323,
            "username": "git—user1",
            "web_url": "https://git.tencent.com/u/git—user1",
            "name": "git—user1",
            "state": "active",
            "avatar_url": "git.tencent.com/uploads/user/avatar/11323/a75ba2738c7a409cab1d15dd993149aa.jpg"
    },
    "milestone": null,
    "project_id": 45595,
    "work_in_progress": false,
    "upvotes": 0,
    "downvotes": 0
}

# 查询项目合并请求是否有冲突

查询项目下某个指定合并请求是否有冲突

GET /api/v3/projects/:id/merge_request/:merge_request_id/merge_conflict_check

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id

返回值：

{
    "has_conflicts": true,
    "base_commit": "48a29c1b4c9df2bc7fa8f3c2acf7978562863dfc",
    "target_commit": "0eb9f8c1302ba40835bec8050e7dbed6e4d560ec",
    "conflict_files": [
        "test.txt"
    ]
}

# 查询项目 commit 间是否有冲突

查询项目下两个 commit 是否有冲突

GET /api/v3/projects/:id/merge_request/commit_conflict_check

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
base_commit	String	起始 commit 的 SHA 值 (只支持 40 位的 commit 值)
target_commit	String	目标 commit 的 SHA 值 (只支持 40 位的 commit 值)

返回值：

{
    "has_conflicts": true,
    "base_commit": "48a29c1b4c9df2bc7fa8f3c2acf7978562863dfc",
    "target_commit": "0eb9f8c1302ba40835bec8050e7dbed6e4d560ec",
    "conflict_files": [
        "test.txt",
        "test1.txt"
    ],
    "resolve_conflicts_url": null
}

# 查询用户是否订阅请求合并

在项目里查询是否订阅了某个指定合并请求

GET /api/v3/projects/:id/merge_request/:merge_request_id/subscribe

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	请求合并的 id

返回值：

true or false

# 订阅请求合并

在项目内订阅某个指定的合并请求

PUT /api/v3/projects/:id/merge_request/:merge_request_id/subscribe

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id

返回值：

200 或状态码

# 取消订阅合并请求

在项目内取消订阅某个指定的合并请求

PUT /api/v3/projects/:id/merge_request/:merge_request_id/unsubscribe

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id

返回值：

200 或状态码

# 下载 MR 差异文件集

下载指定合并请求的差异文件集

仅支持下载 open 状态的合并请求

GET /api/v3/projects/:id/merge_request/:merge_request_id/changed_files

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id

返回值

文件流

# 产生 MR 预合并点

提前生成从源分支到目标分支的合并点，此合并点不影响 MR 状态，仅用于 Pre-Merge 检查或者代码评审

注意

仅支持 open 状态的合并请求
在获得 id(commit_id) 后，命令行可通过git fetch origin <commit_id> && git checkout FETCH_HEAD检出到工作区

PUT /api/v3/projects/:id/merge_request/iid/:merge_request_iid/create_pre_merge_commit

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_iid	integer	合并请求的 iid

返回值

{
  "id": "6269835cafdd89e6d8b8d4a4e3738c79206c1d06",
  "message": "Pre-Merge for merge request !1\n\nmerge master (11a63fa0) with dev (556c115d)\n\nConflicts:\n* README.md",
  "parent_ids": [
    "11a63fa022906668338166ce7f2e7bf35d502285",
    "556c115d64e7fb4be1c8b35c4ae32116712babe3"
  ],
  "authored_date": "2012-06-07T07:38:33+0000",
  "author_name": "git_user1",
  "author_email": "git_user1@tencent.com",
  "committed_date": "2012-06-07T07:38:33+0000",
  "committer_name": "git_user1",
  "committer_email": "git_user1@tencent.com",
  "title": "Pre-Merge for merge request !1",
  "created_at": "2012-06-07T07:38:33+0000",
  "short_id": "6269835c",
  "conflict": true,
  "conflict_files": [
    "README.md"
  ]
}

# 回退合并请求

在项目内回滚某个指定的合并请求

POST /api/v3/projects/:id/merge_request/:merge_request_id/revert

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
merge_request_id	integer	合并请求的 id
target_branch	string	回退合并请求的目标分支
create_mr	boolean（可选）	回退合并请求是否生成新的合并请求（默认值为 false）

返回值：

200 或相关状态码

合并请求

← 项目 hook owners 相关 →