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.

After a site administrator upgrades your Enterprise Server instance to Enterprise Server 3.9 or later, the REST API will be versioned. To learn how to find your instance's version, see "About versions of GitHub Docs". For more information, see "About API versioning."

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 `application/vnd.github+json` is recommended.
Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). Default: `30`
`page` integer Page number of the results to fetch. Default: `1`
`direction` string The direction to sort the results by. Default: `desc` Can be one of: `asc`, `desc`
`sort` string Default: `created` Can be one of: `created`, `updated`, `name`

HTTP response status codes for "List pre-receive environments"

Status code	Description
`200`	OK

Code samples for "List pre-receive environments"

get/admin/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 `application/vnd.github+json` is recommended.
Body parameters
Name, Type, Description
`name` string Required The new pre-receive environment's name.
`image_url` string Required URL 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"

post/admin/pre-receive-environments

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 `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`pre_receive_environment_id` integer Required The 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"

get/admin/pre-receive-environments/{pre_receive_environment_id}

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 `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`pre_receive_environment_id` integer Required The 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"

patch/admin/pre-receive-environments/{pre_receive_environment_id}

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 `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`pre_receive_environment_id` integer Required The 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"

delete/admin/pre-receive-environments/{pre_receive_environment_id}

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 `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`pre_receive_environment_id` integer Required The 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"

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>" \
  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 `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`pre_receive_environment_id` integer Required The 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"

get/admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest

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
}