# 适用于部署密钥的 REST API 终结点

使用 REST API 创建和管理部署密钥。

## 关于部署密钥

可以使用部署密钥（即授予对单个存储库的访问权限的 SSH 密钥）从你的 GitHub Enterprise Server 实例上的存储库启动项目到服务器。 GitHub 将密钥的公共部分直接附加到存储库而不是个人帐户，密钥的私有部分仍保留在服务器上。 有关详细信息，请参阅“[执行部署](/zh/enterprise-server@3.18/rest/guides/delivering-deployments)”。

可以使用以下 API 终结点或使用 GitHub Web 界面设置部署密钥。 若要了解如何在 Web 界面中设置部署密钥，请参阅 [管理部署密钥](/zh/enterprise-server@3.18/authentication/connecting-to-github-with-ssh/managing-deploy-keys)。

如果组织或企业所有者设置了限制密钥使用的策略，则你可能无法创建部署密钥。 此外，如果在组织或企业级别启用此策略，则现有部署密钥可能会被禁用。 有关详细信息，请参阅 [在企业中实施仓库管理策略](/zh/enterprise-server@3.18/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-deploy-keys) 和 [限制在您的组织中使用部署密钥](/zh/enterprise-server@3.18/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization)。

在某些情况下，其他活动将删除部署密钥：

* 如果使用 personal access token 创建了部署密钥，删除 personal access token 也会删除该部署密钥。 重新生成 personal access token 不会删除部署密钥。
* 如果通过 OAuth app 令牌创建部署密钥，则撤销该令牌也会删除部署密钥。

相反，以下活动不会删除部署密钥：

* 如果使用用户访问令牌创建 GitHub App 部署密钥，则撤销令牌不会删除部署密钥。
* 如果使用安装访问令牌创建 GitHub App 部署密钥，则卸载或删除应用不会删除部署密钥。
* 如果使用 a personal access token创建部署密钥，则 personal access token 重新生成部署密钥不会删除部署密钥。

> \[!NOTE]
> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2022-11-28`. Curl examples below omit these standard headers for brevity.

## List deploy keys

```
GET /repos/{owner}/{repo}/keys
```

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys
```

**Response schema (Status: 200):**

Array of `Deploy Key`:

* `id`: required, integer
* `key`: required, string
* `url`: required, string
* `title`: required, string
* `verified`: required, boolean
* `created_at`: required, string
* `read_only`: required, boolean
* `added_by`: string or null
* `last_used`: string or null, format: date-time
* `enabled`: boolean

## Create a deploy key

```
POST /repos/{owner}/{repo}/keys
```

You can create a read-only deploy key.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

#### Body parameters

* **`title`** (string)
  A name for the key.

* **`key`** (string) (required)
  The contents of the key.

* **`read_only`** (boolean)
  If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
  Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "Repository permission levels for an organization" and "Permission levels for a user account repository."

### HTTP response status codes

* **201** - Created

* **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys \
  -d '{
  "title": "octocat@octomac",
  "key": "ssh-rsa AAA...",
  "read_only": true
}'
```

**Response schema (Status: 201):**

* `id`: required, integer
* `key`: required, string
* `url`: required, string
* `title`: required, string
* `verified`: required, boolean
* `created_at`: required, string
* `read_only`: required, boolean
* `added_by`: string or null
* `last_used`: string or null, format: date-time
* `enabled`: boolean

## Get a deploy key

```
GET /repos/{owner}/{repo}/keys/{key_id}
```

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

* **`key_id`** (integer) (required)
  The unique identifier of the key.

### HTTP response status codes

* **200** - OK

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys/KEY_ID
```

**Response schema (Status: 200):**

Same response schema as [Create a deploy key](#create-a-deploy-key).

## Delete a deploy key

```
DELETE /repos/{owner}/{repo}/keys/{key_id}
```

Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

* **`key_id`** (integer) (required)
  The unique identifier of the key.

### HTTP response status codes

* **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys/KEY_ID
```

**Response schema (Status: 204):**