提交 API

该 API 操作 仓库提交。阅读更多关于极狐GitLab 特定信息 的提交。

响应#

此 API 的响应中的某些日期字段是或可能看起来是重复的信息：

• created_at 字段仅用于与其他极狐GitLab API 的一致性。它始终与 committed_date 字段相同。
• committed_date 和 authored_date 字段是从不同来源生成的，可能不相同。

列出仓库提交#

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

plaintext
GET /projects/:id/repository/commits

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits"

示例响应：

json
1[
2  {
3    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
4    "short_id": "ed899a2f4b5",
5    "title": "Replace sanitize with escape once",
6    "author_name": "Example User",
7    "author_email": "user@example.com",
8    "authored_date": "2021-09-20T11:50:22.001+00:00",
9    "committer_name": "Administrator",
10    "committer_email": "admin@example.com",
11    "committed_date": "2021-09-20T11:50:22.001+00:00",
12    "created_at": "2021-09-20T11:50:22.001+00:00",
13    "message": "Replace sanitize with escape once",
14    "parent_ids": [
15      "6104942438c14ec7bd21c6cd5bd995272b3faff6"
16    ],
17    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746",
18    "trailers": {},
19    "extended_trailers": {}
20  },
21  {
22    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
23    "short_id": "6104942438c",
24    "title": "Sanitize for network graph",
25    "author_name": "randx",
26    "author_email": "user@example.com",
27    "committer_name": "ExampleName",
28    "committer_email": "user@example.com",
29    "created_at": "2021-09-20T09:06:12.201+00:00",
30    "message": "Sanitize for network graph\nCc: John Doe <johndoe@gitlab.com>\nCc: Jane Doe <janedoe@gitlab.com>",
31    "parent_ids": [
32      "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
33    ],
34    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746",
35    "trailers": { "Cc": "Jane Doe <janedoe@gitlab.com>" },
36    "extended_trailers": { "Cc": ["John Doe <johndoe@gitlab.com>", "Jane Doe <janedoe@gitlab.com>"] }
37  }
38]

创建一个包含多个文件和动作的提交#

通过发布 JSON 有效负载来创建提交

plaintext
POST /projects/:id/repository/commits

shell
1PAYLOAD=$(cat << 'JSON'
2{
3  "branch": "main",
4  "commit_message": "some commit message",
5  "actions": [
6    {
7      "action": "create",
8      "file_path": "foo/bar",
9      "content": "some content"
10    },
11    {
12      "action": "delete",
13      "file_path": "foo/bar2"
14    },
15    {
16      "action": "move",
17      "file_path": "foo/bar3",
18      "previous_path": "foo/bar4",
19      "content": "some content"
20    },
21    {
22      "action": "update",
23      "file_path": "foo/bar5",
24      "content": "new content"
25    },
26    {
27      "action": "chmod",
28      "file_path": "foo/bar5",
29      "execute_filemode": true
30    }
31  ]
32}
33JSON
34)
35curl --request POST \
36  --header "PRIVATE-TOKEN: <your_access_token>" \
37  --header "Content-Type: application/json" \
38  --data "$PAYLOAD" \
39  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits"

示例响应：

json
1{
2  "id": "ed899a2f4b50b4370feeea94676502b42383c746",
3  "short_id": "ed899a2f4b5",
4  "title": "some commit message",
5  "author_name": "Example User",
6  "author_email": "user@example.com",
7  "committer_name": "Example User",
8  "committer_email": "user@example.com",
9  "created_at": "2016-09-20T09:26:24.000-07:00",
10  "message": "some commit message",
11  "parent_ids": [
12    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
13  ],
14  "committed_date": "2016-09-20T09:26:24.000-07:00",
15  "authored_date": "2016-09-20T09:26:24.000-07:00",
16  "stats": {
17    "additions": 2,
18    "deletions": 2,
19    "total": 4
20  },
21  "status": null,
22  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
23}

极狐GitLab 支持 表单编码。以下是使用表单编码的提交 API 示例：

shell
1curl --request POST \
2     --form "branch=main" \
3     --form "commit_message=some commit message" \
4     --form "start_branch=main" \
5     --form "actions[][action]=create" \
6     --form "actions[][file_path]=foo/bar" \
7     --form "actions[][content]=</path/to/local.file" \
8     --form "actions[][action]=delete" \
9     --form "actions[][file_path]=foo/bar2" \
10     --form "actions[][action]=move" \
11     --form "actions[][file_path]=foo/bar3" \
12     --form "actions[][previous_path]=foo/bar4" \
13     --form "actions[][content]=</path/to/local1.file" \
14     --form "actions[][action]=update" \
15     --form "actions[][file_path]=foo/bar5" \
16     --form "actions[][content]=</path/to/local2.file" \
17     --form "actions[][action]=chmod" \
18     --form "actions[][file_path]=foo/bar5" \
19     --form "actions[][execute_filemode]=true" \
20     --header "PRIVATE-TOKEN: <your_access_token>" \
21     "https://gitlab.example.com/api/v4/projects/1/repository/commits"

获取单个提交#

通过提交哈希或分支或标签的名称获取特定提交。

plaintext
GET /projects/:id/repository/commits/:sha

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main"

示例响应：

json
1{
2  "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
3  "short_id": "6104942438c",
4  "title": "Sanitize for network graph",
5  "author_name": "randx",
6  "author_email": "user@example.com",
7  "committer_name": "Dmitriy",
8  "committer_email": "user@example.com",
9  "created_at": "2021-09-20T09:06:12.300+03:00",
10  "message": "Sanitize for network graph",
11  "committed_date": "2021-09-20T09:06:12.300+03:00",
12  "authored_date": "2021-09-20T09:06:12.420+03:00",
13  "parent_ids": [
14    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
15  ],
16  "last_pipeline" : {
17    "id": 8,
18    "ref": "main",
19    "sha": "2dc6aa325a317eda67812f05600bdf0fcdc70ab0",
20    "status": "created"
21  },
22  "stats": {
23    "additions": 15,
24    "deletions": 10,
25    "total": 25
26  },
27  "status": "running",
28  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/6104942438c14ec7bd21c6cd5bd995272b3faff6"
29}

获取提交被推送到的引用#

获取提交被推送到的所有引用（来自分支或标签）。分页参数 page 和 per_page 可用于限制引用列表。

plaintext
GET /projects/:id/repository/commits/:sha/refs

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all"

示例响应：

json
1[
2  {"type": "branch", "name": "'test'"},
3  {"type": "branch", "name": "add-balsamiq-file"},
4  {"type": "branch", "name": "wip"},
5  {"type": "tag", "name": "v1.1.0"}
6 ]

获取提交的序列#

通过从给定提交开始跟随父链接来获取项目中提交的序列号。

此 API 提供的功能与 git rev-list --count 命令对于给定提交 SHA 基本相同。

plaintext
GET /projects/:id/repository/commits/:sha/sequence

参数：

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/sequence"

示例响应：

json
{
  "count": 632
}

选择性提交#

选择性提交一个提交到指定分支。

plaintext
POST /projects/:id/repository/commits/:sha/cherry_pick

参数：

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=main" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/cherry_pick"

示例响应：

json
1{
2  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
3  "short_id": "8b090c1b",
4  "author_name": "Example User",
5  "author_email": "user@example.com",
6  "authored_date": "2016-12-12T20:10:39.000+01:00",
7  "created_at": "2016-12-12T20:10:39.000+01:00",
8  "committer_name": "Administrator",
9  "committer_email": "admin@example.com",
10  "committed_date": "2016-12-12T20:10:39.000+01:00",
11  "title": "Feature added",
12  "message": "Feature added\n\nSigned-off-by: Example User <user@example.com>\n",
13  "parent_ids": [
14    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
15  ],
16  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"
17}

在选择性提交失败的情况下，响应提供了关于原因的上下文：

json
{
  "message": "Sorry, we cannot cherry-pick this commit automatically. This commit may already have been cherry-picked, or a more recent commit may have updated some of its content.",
  "error_code": "empty"
}

在这种情况下，选择性提交失败，因为更改集为空，可能表明提交已存在于目标分支中。另一个可能的错误代码是 conflict，表示存在合并冲突。

当启用 dry_run 时，服务器尝试应用选择性提交但不实际提交任何结果更改。如果选择性提交应用成功，API 响应 200 OK：

json
{
  "dry_run": "success"
}

在失败的情况下，显示的错误与没有干运行时失败的错误相同。

撤销提交#

撤销给定分支中的提交。

plaintext
POST /projects/:id/repository/commits/:sha/revert

参数：

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=main" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert"

示例响应：

json
1{
2  "id":"8b090c1b79a14f2bd9e8a738f717824ff53aebad",
3  "short_id": "8b090c1b",
4  "title":"Revert \"Feature added\"",
5  "created_at":"2018-11-08T15:55:26.000Z",
6  "parent_ids":["a738f717824ff53aebad8b090c1b79a14f2bd9e8"],
7  "message":"Revert \"Feature added\"\n\nThis reverts commit a738f717824ff53aebad8b090c1b79a14f2bd9e8",
8  "author_name":"Administrator",
9  "author_email":"admin@example.com",
10  "authored_date":"2018-11-08T15:55:26.000Z",
11  "committer_name":"Administrator",
12  "committer_email":"admin@example.com",
13  "committed_date":"2018-11-08T15:55:26.000Z",
14  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"
15}

在撤销失败的情况下，响应提供了关于原因的上下文：

json
{
  "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.",
  "error_code": "conflict"
}

在这种情况下，撤销失败，因为尝试撤销生成了合并冲突。另一个可能的错误代码是 empty，表示更改集为空，可能是由于更改已被撤销。

当启用 dry_run 时，服务器尝试应用撤销但不实际提交任何结果更改。如果撤销应用成功，API 响应 200 OK：

json
{
  "dry_run": "success"
}

在失败的情况下，显示的错误与没有干运行时失败的错误相同。

获取提交的差异#

获取项目中提交的差异。

plaintext
GET /projects/:id/repository/commits/:sha/diff

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/diff"

示例响应：

json
1[
2  {
3    "diff": "@@ -71,6 +71,8 @@\n sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production\n sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production\n \n+sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production\n+\n ```\n \n ### 6. Update config files",
4    "new_path": "doc/update/5.4-to-6.0.md",
5    "old_path": "doc/update/5.4-to-6.0.md",
6    "a_mode": null,
7    "b_mode": "100644",
8    "new_file": false,
9    "renamed_file": false,
10    "deleted_file": false
11  }
12]

获取提交的评论#

获取项目中提交的评论。

plaintext
GET /projects/:id/repository/commits/:sha/comments

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/comments"

示例响应：

json
1[
2  {
3    "note": "this code is really nice",
4    "author": {
5      "id": 11,
6      "username": "admin",
7      "email": "admin@local.host",
8      "name": "Administrator",
9      "state": "active",
10      "created_at": "2014-03-06T08:17:35.000Z"
11    }
12  }
13]

发布提交评论#

向提交添加评论。

要在特定文件的特定行发布评论，必须指定完整提交 SHA、path、line，并且 line_type 应为 new。

如果以下至少一个情况有效，则评论将添加到最后一次提交的末尾：

• sha 是分支或标签，且 line 或 path 无效
• line 号无效（不存在）
• path 无效（不存在）

在上述任何情况下，响应的 line、line_type 和 path 设置为 null。

有关其他评论合并请求的方法，请参阅 Notes API 中的 创建新合并请求备注，以及 Discussions API 中的 在合并请求差异中创建新线程。

plaintext
POST /projects/:id/repository/commits/:sha/comments

shell
1curl --request POST \
2  --header "PRIVATE-TOKEN: <your_access_token>" \
3  --form "note=Nice picture\!" \
4  --form "path=README.md" \
5  --form "line=11" \
6  --form "line_type=new" \
7  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments"

示例响应：

json
1{
2   "author" : {
3      "web_url" : "https://gitlab.example.com/janedoe",
4      "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
5      "username" : "janedoe",
6      "state" : "active",
7      "name" : "Jane Doe",
8      "id" : 28
9   },
10   "created_at" : "2016-01-19T09:44:55.600Z",
11   "line_type" : "new",
12   "path" : "README.md",
13   "line" : 11,
14   "note" : "Nice picture!"
15}

获取提交的讨论#

获取项目中提交的讨论。

plaintext
GET /projects/:id/repository/commits/:sha/discussions

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/4604744a1c64de00ff62e1e8a6766919923d2b41/discussions"

示例响应：

json
1[
2  {
3    "id": "4604744a1c64de00ff62e1e8a6766919923d2b41",
4    "individual_note": true,
5    "notes": [
6      {
7        "id": 334686748,
8        "type": null,
9        "body": "Nice piece of code!",
10        "attachment": null,
11        "author" : {
12          "id" : 28,
13          "name" : "Jane Doe",
14          "username" : "janedoe",
15          "web_url" : "https://gitlab.example.com/janedoe",
16          "state" : "active",
17          "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png"
18        },
19        "created_at": "2020-04-30T18:48:11.432Z",
20        "updated_at": "2020-04-30T18:48:11.432Z",
21        "system": false,
22        "noteable_id": null,
23        "noteable_type": "Commit",
24        "resolvable": false,
25        "confidential": null,
26        "noteable_iid": null,
27        "commands_changes": {}
28      }
29    ]
30  }
31]

提交状态#

用于极狐GitLab 的提交状态 API。

列出提交的状态#

列出项目中提交的状态。分页参数 page 和 per_page 可用于限制引用列表。

plaintext
GET /projects/:id/repository/commits/:sha/statuses

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses"

示例响应：

json
1[
2   ...
3
4   {
5      "status" : "pending",
6      "created_at" : "2016-01-19T08:40:25.934Z",
7      "started_at" : null,
8      "name" : "bundler:audit",
9      "allow_failure" : true,
10      "author" : {
11         "username" : "janedoe",
12         "state" : "active",
13         "web_url" : "https://gitlab.example.com/janedoe",
14         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
15         "id" : 28,
16         "name" : "Jane Doe"
17      },
18      "description" : null,
19      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
20      "target_url" : "https://gitlab.example.com/janedoe/gitlab-foss/builds/91",
21      "finished_at" : null,
22      "id" : 91,
23      "ref" : "main"
24   },
25   {
26      "started_at" : null,
27      "name" : "test",
28      "allow_failure" : false,
29      "status" : "pending",
30      "created_at" : "2016-01-19T08:40:25.832Z",
31      "target_url" : "https://gitlab.example.com/janedoe/gitlab-foss/builds/90",
32      "id" : 90,
33      "finished_at" : null,
34      "ref" : "main",
35      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
36      "author" : {
37         "id" : 28,
38         "name" : "Jane Doe",
39         "username" : "janedoe",
40         "web_url" : "https://gitlab.example.com/janedoe",
41         "state" : "active",
42         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png"
43      },
44      "description" : null
45   },
46
47   ...
48]

设置提交的流水线状态#

添加或更新提交的流水线状态。如果提交与合并请求相关联，则 API 调用必须针对合并请求源分支中的提交。

plaintext
POST /projects/:id/statuses/:sha

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"

示例响应：

json
1{
2   "author" : {
3      "web_url" : "https://gitlab.example.com/janedoe",
4      "name" : "Jane Doe",
5      "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
6      "username" : "janedoe",
7      "state" : "active",
8      "id" : 28
9   },
10   "name" : "default",
11   "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
12   "status" : "success",
13   "coverage": 100.0,
14   "description" : null,
15   "id" : 93,
16   "target_url" : null,
17   "ref" : null,
18   "started_at" : null,
19   "created_at" : "2016-01-19T09:05:50.355Z",
20   "allow_failure" : false,
21   "finished_at" : "2016-01-19T09:05:50.365Z"
22}

列出与提交相关的合并请求#

返回最初引入特定提交的合并请求信息。

plaintext
GET /projects/:id/repository/commits/:sha/merge_requests

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests"

示例响应：

json
1[
2   {
3      "id":45,
4      "iid":1,
5      "project_id":35,
6      "title":"Add new file",
7      "description":"",
8      "state":"opened",
9      "created_at":"2018-03-26T17:26:30.916Z",
10      "updated_at":"2018-03-26T17:26:30.916Z",
11      "target_branch":"main",
12      "source_branch":"test-branch",
13      "upvotes":0,
14      "downvotes":0,
15      "author" : {
16        "web_url" : "https://gitlab.example.com/janedoe",
17        "name" : "Jane Doe",
18        "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
19        "username" : "janedoe",
20        "state" : "active",
21        "id" : 28
22      },
23      "assignee":null,
24      "source_project_id":35,
25      "target_project_id":35,
26      "labels":[ ],
27      "draft":false,
28      "work_in_progress":false,
29      "milestone":null,
30      "merge_when_pipeline_succeeds":false,
31      "merge_status":"can_be_merged",
32      "sha":"af5b13261899fb2c0db30abdd0af8b07cb44fdc5",
33      "merge_commit_sha":null,
34      "squash_commit_sha":null,
35      "user_notes_count":0,
36      "discussion_locked":null,
37      "should_remove_source_branch":null,
38      "force_remove_source_branch":false,
39      "web_url":"https://gitlab.example.com/root/test-project/merge_requests/1",
40      "time_stats":{
41         "time_estimate":0,
42         "total_time_spent":0,
43         "human_time_estimate":null,
44         "human_total_time_spent":null
45      }
46   }
47]

获取提交签名#

获取提交的 签名，如果它已签名。对于未签名的提交，结果为 404 响应。

plaintext
GET /projects/:id/repository/commits/:sha/signature

参数：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature"

如果提交是 GPG 签名的示例响应：

json
1{
2  "signature_type": "PGP",
3  "verification_status": "verified",
4  "gpg_key_id": 1,
5  "gpg_key_primary_keyid": "8254AAB3FBD54AC9",
6  "gpg_key_user_name": "John Doe",
7  "gpg_key_user_email": "johndoe@example.com",
8  "gpg_key_subkey_id": null,
9  "commit_source": "gitaly"
10}

示例响应，如果提交是使用 SSH 签名：

json
1{
2  "signature_type": "SSH",
3  "verification_status": "verified",
4  "key": {
5    "id": 11,
6    "title": "Key",
7    "created_at": "2023-05-08T09:12:38.503Z",
8    "expires_at": "2024-05-07T00:00:00.000Z",
9    "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILZzYDq6DhLp3aX84DGIV3F6Vf+Ae4yCTTz7RnqMJOlR MyKey)",
10    "usage_type": "auth_and_signing"
11  },
12  "commit_source": "gitaly"
13}

示例响应，如果提交是 X.509 签名：

json
1{
2  "signature_type": "X509",
3  "verification_status": "unverified",
4  "x509_certificate": {
5    "id": 1,
6    "subject": "CN=gitlab@example.org,OU=Example,O=World",
7    "subject_key_identifier": "BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC",
8    "email": "gitlab@example.org",
9    "serial_number": 278969561018901340486471282831158785578,
10    "certificate_status": "good",
11    "x509_issuer": {
12      "id": 1,
13      "subject": "CN=PKI,OU=Example,O=World",
14      "subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB",
15      "crl_url": "http://example.com/pki.crl"
16    }
17  },
18  "commit_source": "gitaly"
19}

示例响应，如果提交是未签名：

json
{
  "message": "404 GPG Signature Not Found"
}