此版本的 GitHub Enterprise Server 已于以下日期停止服务 2024-07-09. 即使针对重大安全问题，也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能，请升级到最新版本的 GitHub Enterprise。 如需升级帮助，请联系 GitHub Enterprise 支持。

REST API 现已经过版本控制。 有关详细信息，请参阅“关于 API 版本控制”。

适用于预接收环境的 REST API 终结点

使用 REST API 创建、列出、更新和删除预接收挂钩的环境。

关于预接收环境

这些终结点仅适用于经过身份验证的网站管理员。 普通用户将收到 404 响应。

对象属性

预接收环境

名称Type说明
namestringUI 中显示的环境名称。
image_urlstring将要下载并解压缩的 tarball 的 URL。
default_environmentboolean这是否是 GitHub Enterprise Server 附带的默认环境。
downloadobject此环境的下载状态。
hooks_countinteger使用此环境的预接收挂钩数量。

预接收环境下载

名称Type说明
statestring最近下载的状态。
downloaded_atstring最近下载开始的时间。
messagestring在失败时生成任何错误消息。

state 的可能值为 not_started、in_progress、success、failed。

List pre-receive environments

“List pre-receive environments”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

查询参数
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

默认: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

默认: 1

direction string

The direction to sort the results by.

默认: desc

可以是以下选项之一: asc, desc

sort string

默认: created

可以是以下选项之一: created, updated, name

“List pre-receive environments”的 HTTP 响应状态代码

状态代码说明
200

OK

“List pre-receive environments”的示例代码

请求示例

get/admin/pre-receive-environments
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments

Response

Status: 200
[ { "id": 1, "name": "Default", "image_url": "githubenterprise://internal", "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1", "html_url": "https://github.example.com/admin/pre-receive-environments/1", "default_environment": true, "created_at": "2016-05-20T11:35:45-05:00", "hooks_count": 14, "download": { "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest", "state": "not_started", "downloaded_at": "2016-05-26T07:42:53-05:00", "message": null } }, { "id": 2, "name": "DevTools Hook Env", "image_url": "https://my_file_server/path/to/devtools_env.tar.gz", "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2", "html_url": "https://github.example.com/admin/pre-receive-environments/2", "default_environment": false, "created_at": "2016-05-20T11:35:45-05:00", "hooks_count": 1, "download": { "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest", "state": "success", "downloaded_at": "2016-05-26T07:42:53-05:00", "message": null } } ]

Create a pre-receive environment

“Create a pre-receive environment”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

正文参数
name string 必须

The new pre-receive environment's name.

image_url string 必须

URL from which to download a tarball of this environment.

“Create a pre-receive environment”的 HTTP 响应状态代码

状态代码说明
201

Created

“Create a pre-receive environment”的示例代码

请求示例

post/admin/pre-receive-environments
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments \ -d '{"name":"DevTools Hook Env","image_url":"https://my_file_server/path/to/devtools_env.tar.gz"}'

Response

Status: 201
{ "id": 2, "name": "DevTools Hook Env", "image_url": "https://my_file_server/path/to/devtools_env.tar.gz", "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2", "html_url": "https://github.example.com/admin/pre-receive-environments/2", "default_environment": false, "created_at": "2016-05-20T11:35:45-05:00", "hooks_count": 1, "download": { "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest", "state": "not_started", "downloaded_at": null, "message": null } }

Get a pre-receive environment

“Get a pre-receive environment”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

路径参数
pre_receive_environment_id integer 必须

The unique identifier of the pre-receive environment.

“Get a pre-receive environment”的 HTTP 响应状态代码

状态代码说明
200

OK

“Get a pre-receive environment”的示例代码

请求示例

get/admin/pre-receive-environments/{pre_receive_environment_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

Response

Status: 200
{ "id": 2, "name": "DevTools Hook Env", "image_url": "https://my_file_server/path/to/devtools_env.tar.gz", "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2", "html_url": "https://github.example.com/admin/pre-receive-environments/2", "default_environment": false, "created_at": "2016-05-20T11:35:45-05:00", "hooks_count": 1, "download": { "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest", "state": "not_started", "downloaded_at": null, "message": null } }

Update a pre-receive environment

You cannot modify the default environment. If you attempt to modify the default environment, you will receive a 422 Unprocessable Entity response.

“Update a pre-receive environment”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

路径参数
pre_receive_environment_id integer 必须

The unique identifier of the pre-receive environment.

正文参数
name string

This pre-receive environment's new name.

image_url string

URL from which to download a tarball of this environment.

“Update a pre-receive environment”的 HTTP 响应状态代码

状态代码说明
200

OK

422

Client Errors

“Update a pre-receive environment”的示例代码

请求示例

patch/admin/pre-receive-environments/{pre_receive_environment_id}
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID \ -d '{"name":"DevTools Hook Env","image_url":"https://my_file_server/path/to/devtools_env.tar.gz"}'

Response

Status: 200
{ "id": 2, "name": "DevTools Hook Env", "image_url": "https://my_file_server/path/to/devtools_env.tar.gz", "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2", "html_url": "https://github.example.com/admin/pre-receive-environments/2", "default_environment": false, "created_at": "2016-05-20T11:35:45-05:00", "hooks_count": 1, "download": { "url": "https://github.example.com/api/v3/admin/pre-receive-environments/2/downloads/latest", "state": "success", "downloaded_at": "2016-05-26T07:42:53-05:00", "message": null } }

Delete a pre-receive environment

If you attempt to delete an environment that cannot be deleted, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Cannot delete environment that has hooks
  • Cannot delete environment when download is in progress

“Delete a pre-receive environment”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

路径参数
pre_receive_environment_id integer 必须

The unique identifier of the pre-receive environment.

“Delete a pre-receive environment”的 HTTP 响应状态代码

状态代码说明
204

No Content

422

Client Errors

“Delete a pre-receive environment”的示例代码

请求示例

delete/admin/pre-receive-environments/{pre_receive_environment_id}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID

Response

Status: 204

Start a pre-receive environment download

Triggers a new download of the environment tarball from the environment's image_url. When the download is finished, the newly downloaded tarball will overwrite the existing environment.

If a download cannot be triggered, you will receive a 422 Unprocessable Entity response.

The possible error messages are:

  • Cannot modify or delete the default environment
  • Can not start a new download when a download is in progress

“Start a pre-receive environment download”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

路径参数
pre_receive_environment_id integer 必须

The unique identifier of the pre-receive environment.

“Start a pre-receive environment download”的 HTTP 响应状态代码

状态代码说明
202

Accepted

422

Client Errors

“Start a pre-receive environment download”的示例代码

请求示例

post/admin/pre-receive-environments/{pre_receive_environment_id}/downloads
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID/downloads

Response

Status: 202
{ "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest", "state": "not_started", "downloaded_at": null, "message": null }

Get the download status for a pre-receive environment

In addition to seeing the download status at the "Get a pre-receive environment" endpoint, there is also this separate endpoint for just the download status.

“Get the download status for a pre-receive environment”的参数

标头
accept string

Setting to application/vnd.github+json is recommended.

路径参数
pre_receive_environment_id integer 必须

The unique identifier of the pre-receive environment.

“Get the download status for a pre-receive environment”的 HTTP 响应状态代码

状态代码说明
200

OK

“Get the download status for a pre-receive environment”的示例代码

请求示例

get/admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-environments/PRE_RECEIVE_ENVIRONMENT_ID/downloads/latest

Response

Status: 200
{ "url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest", "state": "success", "downloaded_at": "2016-05-26T07:42:53-05:00", "message": null }