# Deployments API

> 原文：[https://docs.gitlab.com/ee/api/deployments.html](https://docs.gitlab.com/ee/api/deployments.html)

*   [List project deployments](#list-project-deployments)
*   [Get a specific deployment](#get-a-specific-deployment)
*   [Create a deployment](#create-a-deployment)
*   [Updating a deployment](#updating-a-deployment)
*   [List of merge requests associated with a deployment](#list-of-merge-requests-associated-with-a-deployment)

# Deployments API[](#deployments-api "Permalink")

## List project deployments[](#list-project-deployments "Permalink")

获取项目中的部署列表.

```
GET /projects/:id/deployments 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `order_by` | string | no | 返回按`id`或`iid`或`created_at`或`updated_at`或`ref`字段排序的部署. 默认为`id` |
| `sort` | string | no | 返回按`asc`或`desc`排列的部署. 默认为`asc` |
| `updated_after` | datetime | no | 返回指定日期之后更新的部署 |
| `updated_before` | datetime | no | 返回在指定日期之前更新的部署 |
| `environment` | string | no | 用于过滤部署的环境名称 |
| `status` | string | no | 用来过滤部署的状态 |

status 属性可以是以下值之一：

*   created
*   running
*   success
*   failed
*   canceled

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

回应范例

```
[  {  "created_at":  "2016-08-11T07:36:40.222Z",  "updated_at":  "2016-08-11T07:38:12.414Z",  "status":  "created",  "deployable":  {  "commit":  {  "author_email":  "admin@example.com",  "author_name":  "Administrator",  "created_at":  "2016-08-11T09:36:01.000+02:00",  "id":  "99d03678b90d914dbb1b109132516d71a4a03ea8",  "message":  "Merge branch 'new-title' into 'master'\r\n\r\nUpdate README\r\n\r\n\r\n\r\nSee merge request !1",  "short_id":  "99d03678",  "title":  "Merge branch 'new-title' into 'master'\r"  },  "coverage":  null,  "created_at":  "2016-08-11T07:36:27.357Z",  "finished_at":  "2016-08-11T07:36:39.851Z",  "id":  657,  "name":  "deploy",  "ref":  "master",  "runner":  null,  "stage":  "deploy",  "started_at":  null,  "status":  "success",  "tag":  false,  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://gitlab.dev/root",  "created_at":  "2015-12-21T13:14:24.077Z",  "bio":  null,  "location":  null,  "public_email":  "",  "skype":  "",  "linkedin":  "",  "twitter":  "",  "website_url":  "",  "organization":  ""  },  "pipeline":  {  "created_at":  "2016-08-11T02:12:10.222Z",  "id":  36,  "ref":  "master",  "sha":  "99d03678b90d914dbb1b109132516d71a4a03ea8",  "status":  "success",  "updated_at":  "2016-08-11T02:12:10.222Z",  "web_url":  "http://gitlab.dev/root/project/pipelines/12"  }  },  "environment":  {  "external_url":  "https://about.gitlab.com",  "id":  9,  "name":  "production"  },  "id":  41,  "iid":  1,  "ref":  "master",  "sha":  "99d03678b90d914dbb1b109132516d71a4a03ea8",  "user":  {  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "id":  1,  "name":  "Administrator",  "state":  "active",  "username":  "root",  "web_url":  "http://localhost:3000/root"  }  },  {  "created_at":  "2016-08-11T11:32:35.444Z",  "updated_at":  "2016-08-11T11:34:01.123Z",  "status":  "created",  "deployable":  {  "commit":  {  "author_email":  "admin@example.com",  "author_name":  "Administrator",  "created_at":  "2016-08-11T13:28:26.000+02:00",  "id":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "message":  "Merge branch 'rename-readme' into 'master'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2",  "short_id":  "a91957a8",  "title":  "Merge branch 'rename-readme' into 'master'\r"  },  "coverage":  null,  "created_at":  "2016-08-11T11:32:24.456Z",  "finished_at":  "2016-08-11T11:32:35.145Z",  "id":  664,  "name":  "deploy",  "ref":  "master",  "runner":  null,  "stage":  "deploy",  "started_at":  null,  "status":  "success",  "tag":  false,  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://gitlab.dev/root",  "created_at":  "2015-12-21T13:14:24.077Z",  "bio":  null,  "location":  null,  "public_email":  "",  "skype":  "",  "linkedin":  "",  "twitter":  "",  "website_url":  "",  "organization":  ""  },  "pipeline":  {  "created_at":  "2016-08-11T07:43:52.143Z",  "id":  37,  "ref":  "master",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "status":  "success",  "updated_at":  "2016-08-11T07:43:52.143Z",  "web_url":  "http://gitlab.dev/root/project/pipelines/13"  }  },  "environment":  {  "external_url":  "https://about.gitlab.com",  "id":  9,  "name":  "production"  },  "id":  42,  "iid":  2,  "ref":  "master",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "user":  {  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "id":  1,  "name":  "Administrator",  "state":  "active",  "username":  "root",  "web_url":  "http://localhost:3000/root"  }  }  ] 
```

## Get a specific deployment[](#get-a-specific-deployment "Permalink")

```
GET /projects/:id/deployments/:deployment_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `deployment_id` | integer | yes | 部署的 ID |

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

回应范例

```
{  "id":  42,  "iid":  2,  "ref":  "master",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "created_at":  "2016-08-11T11:32:35.444Z",  "updated_at":  "2016-08-11T11:34:01.123Z",  "user":  {  "name":  "Administrator",  "username":  "root",  "id":  1,  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://localhost:3000/root"  },  "environment":  {  "id":  9,  "name":  "production",  "external_url":  "https://about.gitlab.com"  },  "deployable":  {  "id":  664,  "status":  "success",  "stage":  "deploy",  "name":  "deploy",  "ref":  "master",  "tag":  false,  "coverage":  null,  "created_at":  "2016-08-11T11:32:24.456Z",  "started_at":  null,  "finished_at":  "2016-08-11T11:32:35.145Z",  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://gitlab.dev/root",  "created_at":  "2015-12-21T13:14:24.077Z",  "bio":  null,  "location":  null,  "skype":  "",  "linkedin":  "",  "twitter":  "",  "website_url":  "",  "organization":  ""  },  "commit":  {  "id":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "short_id":  "a91957a8",  "title":  "Merge branch 'rename-readme' into 'master'\r",  "author_name":  "Administrator",  "author_email":  "admin@example.com",  "created_at":  "2016-08-11T13:28:26.000+02:00",  "message":  "Merge branch 'rename-readme' into 'master'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2"  },  "pipeline":  {  "created_at":  "2016-08-11T07:43:52.143Z",  "id":  42,  "ref":  "master",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "status":  "success",  "updated_at":  "2016-08-11T07:43:52.143Z",  "web_url":  "http://gitlab.dev/root/project/pipelines/5"  }  "runner":  null  }  } 
```

## Create a deployment[](#create-a-deployment "Permalink")

```
POST /projects/:id/deployments 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `environment` | string | yes | 要为其创建部署的环境的名称 |
| `sha` | string | yes | 部署的提交的 SHA |
| `ref` | string | yes | 部署的分支或标记的名称 |
| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) |
| `status` | string | yes | 部署状态 |

状态可以是以下值之一：

*   created
*   running
*   success
*   failed
*   canceled

```
curl --data "environment=production&sha=a91957a858320c0e17f3a0eca7cfacbff50ea29a&ref=master&tag=false&status=success" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments" 
```

响应示例：

```
{  "id":  42,  "iid":  2,  "ref":  "master",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "created_at":  "2016-08-11T11:32:35.444Z",  "status":  "success",  "user":  {  "name":  "Administrator",  "username":  "root",  "id":  1,  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://localhost:3000/root"  },  "environment":  {  "id":  9,  "name":  "production",  "external_url":  "https://about.gitlab.com"  },  "deployable":  null  } 
```

## Updating a deployment[](#updating-a-deployment "Permalink")

```
PUT /projects/:id/deployments/:deployment_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `deployment_id` | integer | yes | 要更新的部署的 ID |
| `status` | string | yes | 部署的新状态 |

```
curl --request PUT --data "status=success" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42" 
```

响应示例：

```
{  "id":  42,  "iid":  2,  "ref":  "master",  "sha":  "a91957a858320c0e17f3a0eca7cfacbff50ea29a",  "created_at":  "2016-08-11T11:32:35.444Z",  "status":  "success",  "user":  {  "name":  "Administrator",  "username":  "root",  "id":  1,  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://localhost:3000/root"  },  "environment":  {  "id":  9,  "name":  "production",  "external_url":  "https://about.gitlab.com"  },  "deployable":  null  } 
```

## List of merge requests associated with a deployment[](#list-of-merge-requests-associated-with-a-deployment "Permalink")

在 GitLab 12.7 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/35739) .

此 API 检索给定部署附带的合并请求列表：

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

它支持与[Merge Requests API](./merge_requests.html#list-merge-requests)相同的参数，并将以相同的格式返回响应：

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42" 
```