部署 API

  • Tier: 基础版,专业版,旗舰版
  • Offering: JihuLab.com, 私有化部署
History

列出项目部署#

获取项目中部署的列表。

plaintext
GET /projects/:id/deployments
属性类型必需描述
idinteger/string项目的 ID 或 URL 编码路径
order_bystring返回按 idiidcreated_atupdated_atfinished_atref 字段排序的部署。默认是 id
sortstring返回按 ascdesc 排序的部署。默认是 asc
updated_afterdatetime返回在指定日期后更新的部署。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
updated_beforedatetime返回在指定日期前更新的部署。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
finished_afterdatetime返回在指定日期后完成的部署。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
finished_beforedatetime返回在指定日期前完成的部署。预期格式为 ISO 8601 (2019-03-15T08:00:00Z)。
environmentstring要通过 环境名称 过滤的部署。
statusstring用于过滤部署的状态。可以是 createdrunningsuccessfailedcanceledblocked
shell
curl --request "GET" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments"

使用 finished_beforefinished_after 时,应将 order_by 指定为 finished_at,并且 status 应为 success

示例响应:

json
1[ 2 { 3 "created_at": "2016-08-11T07:36:40.222Z", 4 "updated_at": "2016-08-11T07:38:12.414Z", 5 "status": "created", 6 "deployable": { 7 "commit": { 8 "author_email": "admin@example.com", 9 "author_name": "Administrator", 10 "created_at": "2016-08-11T09:36:01.000+02:00", 11 "id": "99d03678b90d914dbb1b109132516d71a4a03ea8", 12 "message": "Merge branch 'new-title' into 'main'\r\n\r\nUpdate README\r\n\r\n\r\n\r\nSee merge request !1", 13 "short_id": "99d03678", 14 "title": "Merge branch 'new-title' into 'main'\r" 15 }, 16 "coverage": null, 17 "created_at": "2016-08-11T07:36:27.357Z", 18 "finished_at": "2016-08-11T07:36:39.851Z", 19 "id": 657, 20 "name": "deploy", 21 "ref": "main", 22 "runner": null, 23 "stage": "deploy", 24 "started_at": null, 25 "status": "success", 26 "tag": false, 27 "project": { 28 "ci_job_token_scope_enabled": false 29 }, 30 "user": { 31 "id": 1, 32 "name": "Administrator", 33 "username": "root", 34 "state": "active", 35 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 36 "web_url": "http://gitlab.dev/root", 37 "created_at": "2015-12-21T13:14:24.077Z", 38 "bio": null, 39 "location": null, 40 "public_email": "", 41 "skype": "", 42 "linkedin": "", 43 "twitter": "", 44 "website_url": "", 45 "organization": "" 46 }, 47 "pipeline": { 48 "created_at": "2016-08-11T02:12:10.222Z", 49 "id": 36, 50 "ref": "main", 51 "sha": "99d03678b90d914dbb1b109132516d71a4a03ea8", 52 "status": "success", 53 "updated_at": "2016-08-11T02:12:10.222Z", 54 "web_url": "http://gitlab.dev/root/project/pipelines/12" 55 } 56 }, 57 "environment": { 58 "external_url": "https://gitlab.cn", 59 "id": 9, 60 "name": "production" 61 }, 62 "id": 41, 63 "iid": 1, 64 "ref": "main", 65 "sha": "99d03678b90d914dbb1b109132516d71a4a03ea8", 66 "user": { 67 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 68 "id": 1, 69 "name": "Administrator", 70 "state": "active", 71 "username": "root", 72 "web_url": "http://localhost:3000/root" 73 } 74 }, 75 { 76 "created_at": "2016-08-11T11:32:35.444Z", 77 "updated_at": "2016-08-11T11:34:01.123Z", 78 "status": "created", 79 "deployable": { 80 "commit": { 81 "author_email": "admin@example.com", 82 "author_name": "Administrator", 83 "created_at": "2016-08-11T13:28:26.000+02:00", 84 "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 85 "message": "Merge branch 'rename-readme' into 'main'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2", 86 "short_id": "a91957a8", 87 "title": "Merge branch 'rename-readme' into 'main'\r" 88 }, 89 "coverage": null, 90 "created_at": "2016-08-11T11:32:24.456Z", 91 "finished_at": "2016-08-11T11:32:35.145Z", 92 "id": 664, 93 "name": "deploy", 94 "ref": "main", 95 "runner": null, 96 "stage": "deploy", 97 "started_at": null, 98 "status": "success", 99 "tag": false, 100 "project": { 101 "ci_job_token_scope_enabled": false 102 }, 103 "user": { 104 "id": 1, 105 "name": "Administrator", 106 "username": "root", 107 "state": "active", 108 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 109 "web_url": "http://gitlab.dev/root", 110 "created_at": "2015-12-21T13:14:24.077Z", 111 "bio": null, 112 "location": null, 113 "public_email": "", 114 "skype": "", 115 "linkedin": "", 116 "twitter": "", 117 "website_url": "", 118 "organization": "" 119 }, 120 "pipeline": { 121 "created_at": "2016-08-11T07:43:52.143Z", 122 "id": 37, 123 "ref": "main", 124 "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 125 "status": "success", 126 "updated_at": "2016-08-11T07:43:52.143Z", 127 "web_url": "http://gitlab.dev/root/project/pipelines/13" 128 } 129 }, 130 "environment": { 131 "external_url": "https://gitlab.cn", 132 "id": 9, 133 "name": "production" 134 }, 135 "id": 42, 136 "iid": 2, 137 "ref": "main", 138 "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 139 "user": { 140 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 141 "id": 1, 142 "name": "Administrator", 143 "state": "active", 144 "username": "root", 145 "web_url": "http://localhost:3000/root" 146 } 147 } 148]

获取特定部署#

plaintext
GET /projects/:id/deployments/:deployment_id
属性类型必需描述
idinteger/string项目的 ID 或 URL 编码路径
deployment_idinteger部署的 ID
shell
curl --request "GET" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments/1"

示例响应:

json
1{ 2 "id": 42, 3 "iid": 2, 4 "ref": "main", 5 "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 6 "created_at": "2016-08-11T11:32:35.444Z", 7 "updated_at": "2016-08-11T11:34:01.123Z", 8 "status": "success", 9 "user": { 10 "name": "Administrator", 11 "username": "root", 12 "id": 1, 13 "state": "active", 14 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 15 "web_url": "http://localhost:3000/root" 16 }, 17 "environment": { 18 "id": 9, 19 "name": "production", 20 "external_url": "https://gitlab.cn" 21 }, 22 "deployable": { 23 "id": 664, 24 "status": "success", 25 "stage": "deploy", 26 "name": "deploy", 27 "ref": "main", 28 "tag": false, 29 "coverage": null, 30 "created_at": "2016-08-11T11:32:24.456Z", 31 "started_at": null, 32 "finished_at": "2016-08-11T11:32:35.145Z", 33 "project": { 34 "ci_job_token_scope_enabled": false 35 }, 36 "user": { 37 "id": 1, 38 "name": "Administrator", 39 "username": "root", 40 "state": "active", 41 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 42 "web_url": "http://gitlab.dev/root", 43 "created_at": "2015-12-21T13:14:24.077Z", 44 "bio": null, 45 "location": null, 46 "skype": "", 47 "linkedin": "", 48 "twitter": "", 49 "website_url": "", 50 "organization": "" 51 }, 52 "commit": { 53 "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 54 "short_id": "a91957a8", 55 "title": "Merge branch 'rename-readme' into 'main'\r", 56 "author_name": "Administrator", 57 "author_email": "admin@example.com", 58 "created_at": "2016-08-11T13:28:26.000+02:00", 59 "message": "Merge branch 'rename-readme' into 'main'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2" 60 }, 61 "pipeline": { 62 "created_at": "2016-08-11T07:43:52.143Z", 63 "id": 42, 64 "ref": "main", 65 "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 66 "status": "success", 67 "updated_at": "2016-08-11T07:43:52.143Z", 68 "web_url": "http://gitlab.dev/root/project/pipelines/5" 69 }, 70 "runner": null 71 } 72}

当配置了多个审批规则时,由极狐GitLab 专业版或旗舰版用户创建的部署包含 approval_summary 属性:

json
1{ 2 "approval_summary": { 3 "rules": [ 4 { 5 "user_id": null, 6 "group_id": 134, 7 "access_level": null, 8 "access_level_description": "qa-group", 9 "required_approvals": 1, 10 "deployment_approvals": [] 11 }, 12 { 13 "user_id": null, 14 "group_id": 135, 15 "access_level": null, 16 "access_level_description": "security-group", 17 "required_approvals": 2, 18 "deployment_approvals": [ 19 { 20 "user": { 21 "id": 100, 22 "username": "security-user-1", 23 "name": "security user-1", 24 "state": "active", 25 "avatar_url": "https://www.gravatar.com/avatar/e130fcd3a1681f41a3de69d10841afa9?s=80&d=identicon", 26 "web_url": "http://localhost:3000/security-user-1" 27 }, 28 "status": "approved", 29 "created_at": "2022-04-11T03:37:03.058Z", 30 "comment": null 31 } 32 ] 33 } 34 ] 35 } 36 ... 37}

创建部署#

plaintext
POST /projects/:id/deployments
属性类型必需描述
idinteger/string项目的 ID 或 URL 编码路径
environmentstring要为其创建部署的 环境名称
shastring要部署的提交的 SHA。
refstring部署的分支或标签名称。
tagboolean一个布尔值,表示部署的引用是否为标签 (true) 或不是 (false)。
statusstring创建的部署状态。可以是 runningsuccessfailedcanceled
shell
curl --request "POST" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data "environment=production&sha=a91957a858320c0e17f3a0eca7cfacbff50ea29a&ref=main&tag=false&status=success" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments"

示例响应:

json
1{ 2 "id": 42, 3 "iid": 2, 4 "ref": "main", 5 "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 6 "created_at": "2016-08-11T11:32:35.444Z", 7 "status": "success", 8 "user": { 9 "name": "Administrator", 10 "username": "root", 11 "id": 1, 12 "state": "active", 13 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 14 "web_url": "http://localhost:3000/root" 15 }, 16 "environment": { 17 "id": 9, 18 "name": "production", 19 "external_url": "https://gitlab.cn" 20 }, 21 "deployable": null 22}

由极狐GitLab 专业版或旗舰版用户创建的部署包含 approvalspending_approval_count 属性:

json
1{ 2 "status": "created", 3 "pending_approval_count": 0, 4 "approvals": [], 5 ... 6}

更新部署#

plaintext
PUT /projects/:id/deployments/:deployment_id
属性类型必需描述
idinteger/string项目的 ID 或 URL 编码路径
deployment_idinteger要更新的部署的 ID。
statusstring部署的新状态。可以是 runningsuccessfailedcanceled
shell
curl --request "PUT" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data "status=success" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments/42"

示例响应:

json
1{ 2 "id": 42, 3 "iid": 2, 4 "ref": "main", 5 "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", 6 "created_at": "2016-08-11T11:32:35.444Z", 7 "status": "success", 8 "user": { 9 "name": "Administrator", 10 "username": "root", 11 "id": 1, 12 "state": "active", 13 "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", 14 "web_url": "http://localhost:3000/root" 15 }, 16 "environment": { 17 "id": 9, 18 "name": "production", 19 "external_url": "https://gitlab.cn" 20 }, 21 "deployable": null 22}

由极狐GitLab 专业版或旗舰版用户创建的部署包含 approvalspending_approval_count 属性:

json
1{ 2 "status": "created", 3 "pending_approval_count": 0, 4 "approvals": [ 5 { 6 "user": { 7 "id": 49, 8 "username": "project_6_bot", 9 "name": "****", 10 "state": "active", 11 "avatar_url": "https://www.gravatar.com/avatar/e83ac685f68ea07553ad3054c738c709?s=80&d=identicon", 12 "web_url": "http://localhost:3000/project_6_bot" 13 }, 14 "status": "approved", 15 "created_at": "2022-02-24T20:22:30.097Z", 16 "comment": "Looks good to me" 17 } 18 ], 19 ... 20}

删除特定部署#

删除不是当前环境的最后一个部署或处于 running 状态的特定部署。

plaintext
DELETE /projects/:id/deployments/:deployment_id
属性类型必需描述
idinteger/string项目的 ID 或 URL 编码路径
deployment_idinteger部署的 ID
shell
curl --request "DELETE" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments/1"

示例响应:

json
{ "message": "204 Deployment destroyed" }
json
{ "message": "403 Forbidden" }
json
{ "message": "400 Cannot destroy running deployment" }
json
{ "message": "400 Deployment currently deployed to environment" }

与部署关联的合并请求列表#

并非所有部署都可以与合并请求关联。有关详细信息,请参见 跟踪部署到环境的合并请求

此 API 检索与给定部署一起交付的合并请求列表:

plaintext
GET /projects/:id/deployments/:deployment_id/merge_requests

它支持与合并请求 API相同的参数,并返回使用相同格式的响应:

shell
curl --request "GET" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments/42/merge_requests"

批准或拒绝被阻止的部署#

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
History
    • 在极狐GitLab 14.7 中引入,使用名为 deployment_approvals功能标志。默认禁用。
    • 在极狐GitLab 14.8 中移除了功能标志。

有关此功能的更多信息,请参见部署审批

plaintext
POST /projects/:id/deployments/:deployment_id/approval
属性类型必需描述
idinteger/string项目的 ID 或 URL 编码路径
deployment_idinteger部署的 ID。
statusstring审批的状态(可以是 approvedrejected)。
commentstring与审批一起的评论
represented_asstring当用户属于多个审批规则时,用于审批的用户/群组/角色名称。
shell
curl --request "POST" \ --data "status=approved&comment=Looks good to me&represented_as=security" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/deployments/1/approval"

示例响应:

json
1{ 2 "user": { 3 "id": 100, 4 "username": "security-user-1", 5 "name": "security user-1", 6 "state": "active", 7 "avatar_url": "https://www.gravatar.com/avatar/e130fcd3a1681f41a3de69d10841afa9?s=80&d=identicon", 8 "web_url": "http://localhost:3000/security-user-1" 9 }, 10 "status": "approved", 11 "created_at": "2022-02-24T20:22:30.097Z", 12 "comment":"Looks good to me" 13}