Commits API

Commits API

获取项目中存储库提交的列表.

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

响应示例：

  1. [  {  "id":  "ed899a2f4b50b4370feeea94676502b42383c746",  "short_id":  "ed899a2f4b5",  "title":  "Replace sanitize with escape once",  "author_name":  "Example User",  "author_email":  "user@example.com",  "authored_date":  "2012-09-20T11:50:22+03:00",  "committer_name":  "Administrator",  "committer_email":  "admin@example.com",  "committed_date":  "2012-09-20T11:50:22+03:00",  "created_at":  "2012-09-20T11:50:22+03:00",  "message":  "Replace sanitize with escape once",  "parent_ids":  [  "6104942438c14ec7bd21c6cd5bd995272b3faff6"  ],  "web_url":  "https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"  },  {  "id":  "6104942438c14ec7bd21c6cd5bd995272b3faff6",  "short_id":  "6104942438c",  "title":  "Sanitize for network graph",  "author_name":  "randx",  "author_email":  "user@example.com",  "committer_name":  "ExampleName",  "committer_email":  "user@example.com",  "created_at":  "2012-09-20T09:06:12+03:00",  "message":  "Sanitize for network graph",  "parent_ids":  [  "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"  ],  "web_url":  "https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"  }  ]

Create a commit with multiple files and actions

在 GitLab 8.13 中引入 .

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

  1. POST /projects/:id/repository/commits
Attribute Type Required Description
id integer/string yes 项目的 ID 或
branch string yes 要提交的分支名称. 要创建一个新分支，还提供start_branch或start_sha ，还可以提供start_project .
commit_message string yes 提交讯息
start_branch string no 从中开始新分支的分支名称
start_sha string no 从以下位置启动新分支的提交的 SHA
start_project integer/string no 从中开始新分支的项目 ID 或项目的URL 编码路径 . 默认为id的值.
actions[] array yes 动作哈希数组要批量提交. 请参阅下表以了解它可以采用的属性.
author_email string no 指定提交作者的电子邮件地址
author_name string no 指定提交作者的姓名
stats boolean no 包括提交统计信息. 默认为 true
force boolean no 如果为true则基于start_branch或start_sha的新提交覆盖目标分支
actions[] Attribute Type Required Description
action string yes 执行， create ， delete ， move ， update ， chmod
file_path string yes 文件的完整路径. 例如 lib/class.rb
previous_path string no 要移动文件的原始完整路径. 例如 lib/class1.rb . 仅考虑move动作.
content string no 除delete ， chmod和move以外的所有文件所必需的文件内容. 未指定content移动动作将保留现有文件内容，而任何其他content值都将覆盖文件内容.
encoding string no text或base64 . text是默认值.
last_commit_id string no 上次已知的文件提交 ID. 仅在更新，移动和删除操作中考虑.
execute_filemode boolean no 当为true/false启用/禁用文件上的 execute 标志. 仅考虑用于chmod操作. 
  1. PAYLOAD=$(cat << 'JSON'
  2. {
  3.   "branch": "master",
  4.   "commit_message": "some commit message",
  5.   "actions": [
  6.     {
  7.       "action": "create",
  8.       "file_path": "foo/bar",
  9.     },
  10.     {
  11.       "action": "delete",
  12.       "file_path": "foo/bar2"
  13.     },
  14.     {
  15.       "action": "move",
  16.       "file_path": "foo/bar3",
  18.       "content": "some content"
  19.     },
  20.     {
  21.       "action": "update",
  22.       "file_path": "foo/bar5",
  23.       "content": "new content"
  24.     },
  25.     {
  26.       "action": "chmod",
  27.       "file_path": "foo/bar5",
  28.       "execute_filemode": true
  29.     }
  30.   ]
  31. } JSON )
  32. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data "$PAYLOAD" "https://gitlab.example.com/api/v4/projects/1/repository/commits"

响应示例：

  1. {  "id":  "ed899a2f4b50b4370feeea94676502b42383c746",  "short_id":  "ed899a2f4b5",  "title":  "some commit message",  "author_name":  "Example User",  "author_email":  "user@example.com",  "committer_name":  "Example User",  "committer_email":  "user@example.com",  "created_at":  "2016-09-20T09:26:24.000-07:00",  "message":  "some commit message",  "parent_ids":  [  "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"  ],  "committed_date":  "2016-09-20T09:26:24.000-07:00",  "authored_date":  "2016-09-20T09:26:24.000-07:00",  "stats":  {  "additions":  2,  "deletions":  2,  "total":  4  },  "status":  null,  "web_url":  "https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"  }

GitLab 支持 . 以下是使用 Commit API 和表单编码的示例：

  1. curl --request POST \
  2.      --form "branch=master" \
  3.      --form "commit_message=some commit message" \
  4.      --form "start_branch=master" \
  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[][execute_filemode]=true" \
  19.      --header "PRIVATE-TOKEN: <your_access_token>" \
  20.      "https://gitlab.example.com/api/v4/projects/1/repository/commits"

Get a single commit

获取由提交哈希或分支或标记的名称标识的特定提交.

  1. GET /projects/:id/repository/commits/:sha

Parameters:

Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的 ID 或URL 编码路径
sha string yes 提交哈希或存储库分支或标记的名称
stats boolean no 包括提交统计信息. 默认为 true 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master"

响应示例：

  1. {  "id":  "6104942438c14ec7bd21c6cd5bd995272b3faff6",  "short_id":  "6104942438c",  "title":  "Sanitize for network graph",  "author_name":  "randx",  "author_email":  "user@example.com",  "committer_name":  "Dmitriy",  "committer_email":  "user@example.com",  "created_at":  "2012-09-20T09:06:12+03:00",  "message":  "Sanitize for network graph",  "committed_date":  "2012-09-20T09:06:12+03:00",  "authored_date":  "2012-09-20T09:06:12+03:00",  "parent_ids":  [  "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"  ],  "last_pipeline"  :  {  "id":  8,  "ref":  "master",  "sha":  "2dc6aa325a317eda67812f05600bdf0fcdc70ab0",  "status":  "created"  },  "stats":  {  "additions":  15,  "deletions":  10,  "total":  25  },  "status":  "running",  "web_url":  "https://gitlab.example.com/thedude/gitlab-foss/-/commit/6104942438c14ec7bd21c6cd5bd995272b3faff6"  }

Get references a commit is pushed to

在 GitLab 10.6 中引入

获取提交已提交的所有引用（从分支或标签）. 分页参数page和per_page可用于限制引用列表.

  1. GET /projects/:id/repository/commits/:sha/refs

Parameters:

Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的 ID 或URL 编码路径
sha string yes 提交哈希
type string no 提交范围. 可能的值是branch ， tag ， all . 默认为all . 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all"

Example response:

  1. [  {"type":  "branch",  "name":  "'test'"},  {"type":  "branch",  "name":  "add-balsamiq-file"},  {"type":  "branch",  "name":  "wip"},  {"type":  "tag",  "name":  "v1.1.0"}  ]

在 GitLab 8.15 中 .

Cherry 选择了对给定分支的提交.

  1. POST /projects/:id/repository/commits/:sha/cherry_pick

Parameters:

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

如果选择失败，响应将提供有关以下原因的上下文：

  1. {  "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"  }

在这种情况下，cherry-pick 失败，因为变更集为空，并且很可能表明提交已存在于目标分支中. 另一个可能的错误代码是conflict ，表示存在合并冲突.

Revert a commit

在 GitLab 11.5 中 .

恢复给定分支中的提交.

  1. POST /projects/:id/repository/commits/:sha/revert

Parameters:

Attribute Type Required Description
id integer/string yes 项目的 ID 或URL 编码的路径
sha string yes 提交 SHA 还原
branch string yes 目标分支名称 
  1. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert"

响应示例：

  1. {  "id":"8b090c1b79a14f2bd9e8a738f717824ff53aebad",  "short_id":  "8b090c1b",  "title":"Revert \"Feature added\"",  "created_at":"2018-11-08T15:55:26.000Z",  "parent_ids":["a738f717824ff53aebad8b090c1b79a14f2bd9e8"],  "message":"Revert \"Feature added\"\n\nThis reverts commit a738f717824ff53aebad8b090c1b79a14f2bd9e8",  "author_name":"Administrator",  "author_email":"admin@example.com",  "authored_date":"2018-11-08T15:55:26.000Z",  "committer_name":"Administrator",  "committer_email":"admin@example.com",  "committed_date":"2018-11-08T15:55:26.000Z",  "web_url":  "https://gitlab.example.com/thedude/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"  }

如果还原失败，则响应将提供有关以下原因的上下文：

  1. {  "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 ，表明变更集为空，这可能是由于变更已被还原.

Get the diff of a commit

获取项目中提交的差异.

  1. GET /projects/:id/repository/commits/:sha/diff

Parameters:

Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或
sha string yes 提交哈希或存储库分支或标记的名称 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/diff"

响应示例：

  1. [  {  "diff":  "--- a/doc/update/5.4-to-6.0.md\n+++ b/doc/update/5.4-to-6.0.md\n@@ -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",  "new_path":  "doc/update/5.4-to-6.0.md",  "old_path":  "doc/update/5.4-to-6.0.md",  "a_mode":  null,  "b_mode":  "100644",  "new_file":  false,  "renamed_file":  false,  "deleted_file":  false  }  ]

Get the comments of a commit

获取项目中提交的注释.

Parameters:

Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的 ID 或URL 编码路径
sha string yes 提交哈希或存储库分支或标记的名称 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/comments"

响应示例：

  1. [  {  "note":  "this code is really nice",  "author":  {  "id":  11,  "username":  "admin",  "email":  "admin@local.host",  "name":  "Administrator",  "state":  "active",  "created_at":  "2014-03-06T08:17:35.000Z"  }  }  ]

在提交中添加评论.

为了在特定文件的特定行中发布评论，您必须指定完整的提交 SHA， path ， line和line_type应该是new .

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

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

  1. POST /projects/:id/repository/commits/:sha/comments
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的 ID 或URL 编码路径
sha string yes 提交 SHA 或存储库分支或标记的名称
note string yes 评论文字
path string no 相对于存储库的文件路径
line integer no 放置评论的行号
line_type string no 线型. 采用new或old的争论 
  1. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "note=Nice picture man\!" --form "path=dudeism.md" --form "line=11" --form "line_type=new" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments"

响应示例：

  1. {  "author"  :  {  "web_url"  :  "https://gitlab.example.com/thedude",  "avatar_url"  :  "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",  "username"  :  "thedude",  "state"  :  "active",  "name"  :  "Jeff Lebowski",  "id"  :  28  },  "created_at"  :  "2016-01-19T09:44:55.600Z",  "line_type"  :  "new",  "path"  :  "dudeism.md",  "line"  :  11,  "note"  :  "Nice picture man!"  }

Get the discussions of a commit

获取项目中提交的讨论.

Parameters:

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

响应示例：

  1. [  {  "id":  "4604744a1c64de00ff62e1e8a6766919923d2b41",  "individual_note":  true,  "notes":  [  {  "id":  334686748,  "type":  null,  "body":  "I'm the Dude, so that's what you call me.",  "attachment":  null,  "author"  :  {  "id"  :  28,  "name"  :  "Jeff Lebowski",  "username"  :  "thedude",  "web_url"  :  "https://gitlab.example.com/thedude",  "state"  :  "active",  "avatar_url"  :  "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"  },  "created_at":  "2020-04-30T18:48:11.432Z",  "updated_at":  "2020-04-30T18:48:11.432Z",  "system":  false,  "noteable_id":  null,  "noteable_type":  "Commit",  "resolvable":  false,  "confidential":  null,  "noteable_iid":  null,  "commands_changes":  {}  }  ]  }  ]

Commit status

从 GitLab 8.1 开始，这是新的提交状态 API.

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

  1. GET /projects/:id/repository/commits/:sha/statuses
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的 ID 或URL 编码路径
sha string yes 提交 SHA
ref string no The name of a repository branch or tag or, if not given, the default branch
stage string no 按过滤，例如test
name string no 按工作名称过滤，例如bundler:audit
all boolean no 返回所有状态，不仅是最新状态 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses

响应示例：

  1. [  ...  {  "status"  :  "pending",  "created_at"  :  "2016-01-19T08:40:25.934Z",  "started_at"  :  null,  "name"  :  "bundler:audit",  "allow_failure"  :  true,  "author"  :  {  "username"  :  "thedude",  "state"  :  "active",  "web_url"  :  "https://gitlab.example.com/thedude",  "avatar_url"  :  "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",  "id"  :  28,  "name"  :  "Jeff Lebowski"  },  "description"  :  null,  "sha"  :  "18f3e63d05582537db6d183d9d557be09e1f90c8",  "target_url"  :  "https://gitlab.example.com/thedude/gitlab-foss/builds/91",  "finished_at"  :  null,  "id"  :  91,  "ref"  :  "master"  },  {  "started_at"  :  null,  "name"  :  "test",  "allow_failure"  :  false,  "status"  :  "pending",  "created_at"  :  "2016-01-19T08:40:25.832Z",  "target_url"  :  "https://gitlab.example.com/thedude/gitlab-foss/builds/90",  "id"  :  90,  "finished_at"  :  null,  "ref"  :  "master",  "sha"  :  "18f3e63d05582537db6d183d9d557be09e1f90c8",  "author"  :  {  "id"  :  28,  "name"  :  "Jeff Lebowski",  "username"  :  "thedude",  "web_url"  :  "https://gitlab.example.com/thedude",  "state"  :  "active",  "avatar_url"  :  "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"  },  "description"  :  null  },  ...  ]

Post the build status to a commit

添加或更新提交的构建状态.

  1. POST /projects/:id/statuses/:sha
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或
sha string yes 提交 SHA
state string yes 状态的状态. 可以是以下之一： pending ， running ， success ， failed ， canceled
ref string no 状态所ref （分支或标签）
name or context string no 区分此状态和其他系统状态的标签. 默认值是default
target_url string no 与该状态关联的目标 URL
description string no 状态的简短描述
coverage float no 总代码覆盖率
pipeline_id integer no 要设置状态的管道的 ID. 在同一 SHA 上有多个管道的情况下使用. 
  1. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"

响应示例：

  1. {  "author"  :  {  "web_url"  :  "https://gitlab.example.com/thedude",  "name"  :  "Jeff Lebowski",  "avatar_url"  :  "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",  "username"  :  "thedude",  "state"  :  "active",  "id"  :  28  },  "name"  :  "default",  "sha"  :  "18f3e63d05582537db6d183d9d557be09e1f90c8",  "status"  :  "success",  "coverage":  100.0,  "description"  :  null,  "id"  :  93,  "target_url"  :  null,  "ref"  :  null,  "started_at"  :  null,  "created_at"  :  "2016-01-19T09:05:50.355Z",  "allow_failure"  :  false,  "finished_at"  :  "2016-01-19T09:05:50.365Z"  }

List Merge Requests associated with a commit

在 GitLab 10.7 中 .

获取与指定提交相关的合并请求列表.

  1. GET /projects/:id/repository/commits/:sha/merge_requests
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或
sha string yes 提交 SHA 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests"

响应示例：

  1. [  {  "id":45,  "iid":1,  "project_id":35,  "title":"Add new file",  "description":"",  "state":"opened",  "created_at":"2018-03-26T17:26:30.916Z",  "updated_at":"2018-03-26T17:26:30.916Z",  "target_branch":"master",  "source_branch":"test-branch",  "upvotes":0,  "downvotes":0,  "author"  :  {  "web_url"  :  "https://gitlab.example.com/thedude",  "name"  :  "Jeff Lebowski",  "avatar_url"  :  "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",  "username"  :  "thedude",  "state"  :  "active",  "id"  :  28  },  "assignee":null,  "source_project_id":35,  "target_project_id":35,  "labels":[  ],  "work_in_progress":false,  "milestone":null,  "merge_when_pipeline_succeeds":false,  "merge_status":"can_be_merged",  "sha":"af5b13261899fb2c0db30abdd0af8b07cb44fdc5",  "merge_commit_sha":null,  "squash_commit_sha":null,  "user_notes_count":0,  "discussion_locked":null,  "should_remove_source_branch":null,  "force_remove_source_branch":false,  "web_url":"http://https://gitlab.example.com/root/test-project/merge_requests/1",  "time_stats":{  "time_estimate":0,  "total_time_spent":0,  "human_time_estimate":null,  "human_total_time_spent":null  }  }  ]

从提交获取 （如果已签名）. 对于未签名的提交，将导致 404 响应.

  1. GET /projects/:id/repository/commits/:sha/signature

Parameters:

Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或
sha string yes 提交哈希或存储库分支或标记的名称 
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature"

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

  1. {  "signature_type":  "PGP",  "verification_status":  "verified",  "gpg_key_id":  1,  "gpg_key_primary_keyid":  "8254AAB3FBD54AC9",  "gpg_key_user_name":  "John Doe",  "gpg_key_user_email":  "johndoe@example.com",  "gpg_key_subkey_id":  null  }

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