Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

We've recently moved some of the REST API documentation. If you can't find what you're looking for, you might try the Actions REST API page.

Ambientes Pre-receive

Use a API REST para criar, listar, atualizar e excluir ambientes para ganchos de pré-recebimento.

Sobre os ambientes de pré-recebimento

Esses pontos de extremidade só estão disponíveis para administradores de site autenticados. Os usuários normais receberão uma resposta 404.

Atributos do objeto

Ambiente pre-receive

NomeTypeDescrição
namestringO nome do ambiente conforme exibido na interface do usuário.
image_urlstringURL do tarball que será baixado e extraído.
default_environmentbooleanSe este é o ambiente-padrão que vem com GitHub Enterprise Server.
downloadobjectStatus do download deste ambiente.
hooks_countintegerO número de hooks de pre-receive que usam este ambiente.

Download do ambiente pre-receive

NomeTypeDescrição
statestringO estado do download mais recente.
downloaded_atstringA hora em que o download mais recente começou.
messagestringEm caso de falha, serão produzidas mensagens de erro.

Os valores possíveis para state são not_started, in_progress, success e failed.

List pre-receive environments

Parameters for "List pre-receive environments"

Headers
Name, Type, Description
acceptstring

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

Query parameters
Name, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

directionstring

The direction to sort the results by.

Default: desc

Can be one of: asc, desc

sortstring

Default: created

Can be one of: created, updated, name

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

Status codeDescription
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
acceptstring

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

Body parameters
Name, Type, Description
namestringRequired

The new pre-receive environment's name.

image_urlstringRequired

URL from which to download a tarball of this environment.

HTTP response status codes for "Create a pre-receive environment"

Status codeDescription
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
acceptstring

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

Path parameters
Name, Type, Description
pre_receive_environment_idintegerRequired

The unique identifier of the pre-receive environment.

HTTP response status codes for "Get a pre-receive environment"

Status codeDescription
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
acceptstring

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

Path parameters
Name, Type, Description
pre_receive_environment_idintegerRequired

The unique identifier of the pre-receive environment.

Body parameters
Name, Type, Description
namestring

This pre-receive environment's new name.

image_urlstring

URL from which to download a tarball of this environment.

HTTP response status codes for "Update a pre-receive environment"

Status codeDescription
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
acceptstring

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

Path parameters
Name, Type, Description
pre_receive_environment_idintegerRequired

The unique identifier of the pre-receive environment.

HTTP response status codes for "Delete a pre-receive environment"

Status codeDescription
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
acceptstring

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

Path parameters
Name, Type, Description
pre_receive_environment_idintegerRequired

The unique identifier of the pre-receive environment.

HTTP response status codes for "Start a pre-receive environment download"

Status codeDescription
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
acceptstring

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

Path parameters
Name, Type, Description
pre_receive_environment_idintegerRequired

The unique identifier of the pre-receive environment.

HTTP response status codes for "Get the download status for a pre-receive environment"

Status codeDescription
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 }