This version of GitHub Enterprise was discontinued on 2023-03-15. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.
Pre-receive Environments
Use the REST API to create, list, update and delete environments for pre-receive hooks.
About pre-receive environments
These endpoints are only available to authenticated site administrators. Normal users will receive a 404
response.
Object attributes
Pre-receive Environment
Name | Type | Description |
---|---|---|
name | string | The name of the environment as displayed in the UI. |
image_url | string | URL to the tarball that will be downloaded and extracted. |
default_environment | boolean | Whether this is the default environment that ships with GitHub Enterprise Server. |
download | object | This environment's download status. |
hooks_count | integer | The number of pre-receive hooks that use this environment. |
Pre-receive Environment Download
Name | Type | Description |
---|---|---|
state | string | The state of the most recent download. |
downloaded_at | string | The time when the most recent download started. |
message | string | On failure, this will have any error messages produced. |
Possible values for state
are not_started
, in_progress
, success
, failed
.
List pre-receive environments
Parameters for "List pre-receive environments"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Query parameters |
Name, Type, Description |
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
direction string The direction to sort the results by. Default: Can be one of: |
sort string Default: Can be one of: |
HTTP response status codes for "List pre-receive environments"
Status code | Description |
---|---|
200 | OK |
Code samples for "List pre-receive environments"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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
Parameters for "Create a pre-receive environment"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Body parameters |
Name, Type, Description |
name string RequiredThe new pre-receive environment's name. |
image_url string RequiredURL from which to download a tarball of this environment. |
HTTP response status codes for "Create a pre-receive environment"
Status code | Description |
---|---|
201 | Created |
Code samples for "Create a pre-receive environment"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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
Parameters for "Get a pre-receive environment"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_environment_id integer RequiredThe unique identifier of the pre-receive environment. |
HTTP response status codes for "Get a pre-receive environment"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get a pre-receive environment"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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.
Parameters for "Update a pre-receive environment"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_environment_id integer RequiredThe unique identifier of the pre-receive environment. |
Body parameters |
Name, Type, Description |
name string This pre-receive environment's new name. |
image_url string URL from which to download a tarball of this environment. |
HTTP response status codes for "Update a pre-receive environment"
Status code | Description |
---|---|
200 | OK |
422 | Client Errors |
Code samples for "Update a pre-receive environment"
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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
Parameters for "Delete a pre-receive environment"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_environment_id integer RequiredThe unique identifier of the pre-receive environment. |
HTTP response status codes for "Delete a pre-receive environment"
Status code | Description |
---|---|
204 | No Content |
422 | Client Errors |
Code samples for "Delete a pre-receive environment"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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
Parameters for "Start a pre-receive environment download"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_environment_id integer RequiredThe unique identifier of the pre-receive environment. |
HTTP response status codes for "Start a pre-receive environment download"
Status code | Description |
---|---|
202 | Accepted |
422 | Client Errors |
Code samples for "Start a pre-receive environment download"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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.
Parameters for "Get the download status for a pre-receive environment"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_environment_id integer RequiredThe unique identifier of the pre-receive environment. |
HTTP response status codes for "Get the download status for a pre-receive environment"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get the download status for a pre-receive environment"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
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
}