• 帮助文档

# 提交

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

# 取得一个提交

返回项目版本库某个特定的提交

GET /api/v3/projects/:id/repository/commits/:sha

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag

返回值：

{
  "id": "6269835cafdd89e6d8b8d4a4e3738c79206c1d06",
  "message": "推送新内容",
  "parent_ids": [
    "11a63fa022906668338166ce7f2e7bf35d502285" 
  ],
  "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": "推送新内容",
  "created_at": "2012-06-07T07:38:33+0000",
  "short_id": "6269835c"
}

# 取得提交的差异

返回项目版本库提交的差异。

GET /api/v3/projects/:id/repository/commits/:sha/diff

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag
path string（可选） 文件路径
ignore_white_space boolean（可选） 有差异的内容是否忽略空白符，默认不忽略

返回值：

[
  {
    "old_path": "git-01",
    "new_path": "git-01",
    "a_mode": 33188,
    "b_mode": 33188,
    "diff": "@@ -16,7 +16,7 @@\n \n \t\t\t<c:if test=\"${ not empty project.description }\">\n \t\t\t\t<div class=\"str-truncated project-home-desc text-left\" style=\"width:250px;\">\n-\t\t\t\t\t\t${ tgfn:markdown( project.description , markupContext) }\n+\t\t\t\t\t\t${ tgfn:renderDescription( project.description , markupContext) }\n \t\t\t\t</div>\n \t\t\t</c:if>\n \t\t</div>\n",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false,
    "is_too_large": false,
    "is_collapse": false,
    "additions": 1,
    "deletions": 0
  }
]

# 下载提交差异文件集

下载指定提交的差异文件集

GET /api/v3/projects/:id/repository/commits/:sha/changed_files

参数：

参数 类型 描述
id integer or string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值

返回值 文件流

# 对一个提交发表评论

向一个提交添加评论，可以选择在一个特定的提交行上添加评论，此时参数path、line和line_type是必需的。

POST /api/v3/projects/:id/repository/commits/:sha/comments

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag
note string 评论内容
path string（可选） 文件路径（文件评论则必填）
line integer（可选） 行号（文件评论可不填或填写为 0）
line_type string（可选） 变更类型，可选old、new

返回值：

{
    "id": 2065302,
    "parent_id": null,
    "body": "api test ",
    "attachment": null,
    "author": {
        "id": 385488,
        "username": "git_user1",
        "web_url": "https://git.tencent.com/u/git_user1",
        "name": "git_user1",
        "state": "active",
        "avatar_url": "https://git.tencent.com/uploads/user/avatar/385488/thumb_0-7-334-334_aaf301d9a1494b9da22914b55df6cd66.png"
    },
    "created_at": "2023-07-06T09:15:03+0000",
    "system": false,
    "risk": 0,
    "resolve_state": 0,
    "line_code": null,
    "commit_id": "f6562bcaea514caf746e717c9172ce7b9f4a5dce",
    "file_path": null,
    "note_position": null,
    "note": "api test "
}

# 取得一个提交的评论

返回项目版本库某个提交的评论

GET /api/v3/projects/:id/repository/commits/:sha/comments

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag

返回值：

[
    {
        "id": 2065302,
        "parent_id": null,
        "body": "add ",
        "attachment": null,
        "author": {
            "id": 385488,
            "username": "git_user1",
            "web_url": "https://git.tencent.com/u/git_user1",
            "name": "git_user1",
            "state": "active",
            "avatar_url": "https://git.tencent.com/uploads/user/avatar/385488/thumb_0-7-334-334_aaf301d9a1494b9da22914b55df6cd66.png"
        },
        "created_at": "2023-07-06T09:15:03+0000",
        "system": false,
        "risk": 0,
        "resolve_state": 0,
        "line_code": null,
        "commit_id": "f6562bcaea514caf746e717c9172ce7b9f4a5dce",
        "file_path": null,
        "note_position": null,
        "note": "add "
    }
]

line_code 以 0_0 结尾的评论说明此评审是文件评论

# 编辑提交的评论

对一个提交的评论进行编辑更新

PUT /api/v3/projects/:id/repository/commits/:sha/notes/:note_id

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag
note_id integer 评论的 id
body string 评论内容

返回值：

{
    "id": 2065303,
    "parent_id": null,
    "body": "编辑评论",
    "attachment": null,
    "author": {
        "id": 385488,
        "username": "git_user1",
        "web_url": "https://git.tencent.com/u/git_user1",
        "name": "git_user1",
        "state": "active",
        "avatar_url": "https://git.tencent.com/uploads/user/avatar/385488/thumb_0-7-334-334_aaf301d9a1494b9da22914b55df6cd66.png"
    },
    "created_at": "2023-08-11T06:36:42+0000",
    "system": false,
    "risk": 0,
    "resolve_state": 0,
    "line_code": "d9ae0472eb6fa20d2297703f8f341f559edcabdf_59_59",
    "commit_id": "93246df90455d0fd8134f196328fff80aae754c2",
    "file_path": "test/unit/node/index.js",
    "note_position": {
        "origin_position": {
            "note_id": 2078647,
            "left_line_num": null,
            "right_line_num": 59,
            "base_commit_sha": "d211a3e1433c470a0927bee324e1c1fcdb4eab1d",
            "start_commit_sha": "93246df90455d0fd8134f196328fff80aae754c2",
            "head_commit_sha": "d211a3e1433c470a0927bee324e1c1fcdb4eab1d",
            "new_path": "test/unit/node/index.js",
            "old_path": "test/unit/node/index.js"
        },
        "outdate_position": null,
        "latest_position": {
            "note_id": 2078647,
            "left_line_num": null,
            "right_line_num": 59,
            "base_commit_sha": "d211a3e1433c470a0927bee324e1c1fcdb4eab1d",
            "start_commit_sha": "93246df90455d0fd8134f196328fff80aae754c2",
            "head_commit_sha": "d211a3e1433c470a0927bee324e1c1fcdb4eab1d",
            "new_path": "test/unit/node/index.js",
            "old_path": "test/unit/node/index.js"
        }
    },
    "note": "编辑评论"
}

# 回复提交的首评论

对提交点的文件上的首评论进行回复

POST /api/v3/projects/:id/repository/commits/:sha/notes/:note_id/replies

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag
note_id integer 评论的 id
body string 回复的内容
{
    "id": 2078426,
    "parent_id": 2078181,
    "body": "回复",
    "attachment": null,
    "author": {
        "id": 385488,
        "username": "git_user1",
        "web_url": "https://git.tencent.com/u/git_user1",
        "name": "git_user1",
        "state": "active",
        "avatar_url": "https://git.tencent.com/uploads/user/avatar/385488/thumb_0-7-334-334_aaf301d9a1494b9da22914b55df6cd66.png"
    },
    "created_at": "2023-08-10T08:41:11+0000",
    "system": false,
    "risk": 0,
    "resolve_state": 0,
    "line_code": "608be78b4032b4dcfbaa13f59c00a48c10d85037_0_1",
    "commit_id": "4b82f3928c45f83aec4e758630a58f6aa66eff0d",
    "file_path": "得到的",
    "note_position": null,
    "note": "回复"
}

# 列出项目版本库所有的提交

返回项目版本库（版本库指定文件或者目录）提交 记录

GET /api/v3/projects/:id/repository/commits

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
ref_name string（可选） 版本库分支 或 tag，默认：默认分支
path string（可选） 文件路径
since yyyy-MM-dd'T'HH:mm:ssZ（可选） 此日期及之后的提交：例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”
until yyyy-MM-dd'T'HH:mm:ssZ（可选） 此日期及之前的提交；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800” ）
page integer（可选） 分页（默认值：1）
per_page integer（可选） 默认页面大小（默认值： 20，最大值： 100）

返回值：

[
  {
    "id": "e9c5aa72c9e22592ee2611d896b730c1a95cc339",
    "short_id": "e9c5aa72",
    "title": "asd",
    "author_name": "git_user1",
    "author_email": "git_user1@tencent.com",
    "created_at": "2012-09-19T09:29:19+0000",
    "message": "asd"
  },
  {
    "id": "11a63fa022906668338166ce7f2e7bf35d502285",
    "short_id": "11a63fa0",
    "title": "dd",
    "author_name": "git_user1",
    "author_email": "git_user1@tencent.com",
    "created_at": "2012-09-19T09:29:19+0000",
    "message": "dd"
  }
]

# 获取某个提交对应的分支和 tag

获取这个提交被推送到项目的哪个分支或 tag

GET /api/v3/projects/:id/repository/commits/:sha/refs

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string commit hash 值、分支名或 tag
type string（可选） branch、tag、或all （默认：all）
page integer（可选） 分页（默认值：1）
per_page integer（可选） 默认页面大小（默认值： 20，最大值： 100）

返回值：

[
    {
        "type": "branch",
        "name": "copy"
    },
    {
        "type": "branch",
        "name": "master"
    },
    {
        "type": "tag",
        "name": "v1.1.8"
    }
]

# 拣选 (Cherry Pick) 操作

将一个 commit 点拣选至另外一个分支

POST /api/v3/projects/:id/repository/commit/cherry_pick

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
source_commit string cherry-pick 的源 commit 点的 SHA 值
target_branch string 目标分支
create_mr boolean（可选） 是否创建合并请求，不传默认为 true
title string（可选） 创建 MR 时的 title，长度不应超过 255 个字符，若不设置则默认为 commit msg 的第一行（create_mr 为 false 时不需要)
description string（可选） 创建 MR 时的描述，默认 commit msg 中除第一行的部分（create_mr 为 false 时不需要)
labels string（可选） 合并请求的标签，多个请用英文逗号分隔（create_mr 为 false 时不需要)
assignee_id integer（可选） 合并请求的负责人 id（create_mr 为 false 时不需要)
reviewers string（可选） 合并请求的评审人 id (只能是 id。多个评审人请用英文逗号分隔)（create_mr 为 false 时不需要)
necessary_reviewers string（可选） 合并请求的必要评审人 id (只能是 id。多个评审人请用英文逗号分隔) （create_mr 为 false 时不需要)
approver_rule integer（可选） 合并请求的评审人规则（create_mr 为 false 时不需要)
-1：所有评审人通过，1：单评审通过，2+：多评审通过 (用>=2 的数字代表需要几位必要评审人通过) (默认取项目配置)
necessary_approver_rule integer（可选） 合并请求的必要评审人规则（create_mr 为 false 时不需要)
-1：所有评审人通过，1：单评审通过，2+：多评审通过 (用>=2 的数字代表需要几位必要评审人通过)，0: 不需要必要评审人即可通过 (默认取项目配置)

当 create_mr 为 true 时 (默认)，返回值：

{
    "labels": [],
    "id": 1590601,
    "title": "--story=0000000",
    "target_project_id": 10709655,
    "target_branch": "hotfix-micky",
    "source_project_id": 10709655,
    "source_branch": "cherry-pick-bef79763",
    "state": "opened",
    "merge_status": "can_be_merged",
    "iid": 5,
    "description": "(cherry picked from commit bef79763)",
    "created_at": "2021-06-29T03:37:45+0000",
    "updated_at": "2021-06-29T03:37:45+0000",
    "resolved_at": null,
    "merge_type": null,
    "assignee": null,
    "author": {
        "id": 86362,
       "username": "git_user1",
       "web_url": "http://git.tencent.com/u/git_user1
        "name": "jacobewu",
        "state": "active",
        "avatar_url": "http://git.tencent.com/assets/images/avatar/no_user_avatar.png"
    },
    "merge_commit_sha": null,
    "milestone": {
        "id": 111157,
        "project_id": 12321,
        "title": "milestone1",
        "state": "active",
        "iid": 1,
        "due_date": "2024-08-15",
        "created_at": "2023-08-16T08:00:25+0000",
        "updated_at": "2023-08-16T08:00:52+0000",
        "description": ""
    },
    "necessary_reviewers": null,
    "suggestion_reviewers": null,
    "work_in_progress": false,
    "project_id": 10709655,
    "upvotes": 0,
    "downvotes": 0
}

当 create_mr 为 false 时，返回值：

{
    "message": "Cherry pick successful!"
}

# 还原一个提交

还原指定分支的某个提交

POST /api/v3/projects/:id/repository/commits/:sha/revert

参数：

参数 类型 描述
id integer 或 string 项目 ID 或 项目全路径 project_full_path
sha string 需要还原的commit sha，支持最低 8 位
branch string 目标分支名称
dry_run boolean(可选) 预检查revert操作是否冲突，不提交任何更改。默认值为 false。

返回值：

{
  "parent_ids": [
    "6b7e337aa5c6118a825c530439755fd894f8f878"
  ],
  "short_id": "120b6d8a",
  "id": "120b6d8a7d7cde22334aaed9a6783d8e11a24bd3",
  "message": "Revert \"Revert \"添加新文件\"\"\n\nThis reverts commit adbd55ca4cb22e95709aa06931e0fe6484ff137c.\n",
  "authored_date": "2025-04-24T02:51:23+0000",
  "author_name": "git_user",
  "author_email": "git_user@tencent.com",
  "committed_date": "2025-04-24T02:51:23+0000",
  "committer_name": "git_user",
  "committer_email": "git_user@tencent.com",
  "created_at": "2025-04-24T02:51:23+0000",
  "title": "Revert \"Revert \"添加新文件\"\""
}

如果还原失败，会返回对应的message:

{
  "message": "Sorry, we cannot revert this commit automatically. This commit may already have been reverted, or a more recent commit may have updated some of its content."
}

设置了dry_run时，会预检查revert操作是否冲突，但实际上不会提交相应的更改(仅检查是否可以 Revert，不会对提交信息校验、Webhook、文件锁等进行检查)。如果检查通过，API 将返回200：

{
  "dry_run": "success"
}

如果检查失败，则会返回与未设置dry_run模式下一致的错误。

lastUpdate: 4/24/2025, 11:08:44 AM

← 项目相关 →