L’API REST est maintenant versionnée. Pour plus d’informations, consultez « À propos des versions de l’API ».

Points de terminaison d’API REST pour les environnements de pré-réception

Utilisez l’API REST pour créer, répertorier, mettre à jour et supprimer des environnements pour les hooks de pré-réception.

À propos des environnements de pré-réception

Ces points de terminaison sont uniquement disponibles pour les administrateurs de site authentifiés. Les utilisateurs normaux recevront une réponse 404.

Remarque

Ces points de terminaison prennent uniquement en charge l’authentification à l’aide d’un personal access token (classic). Pour plus d’informations, consultez « Gestion de vos jetons d’accès personnels ».

Attributs d’objet

Environnement de pré-réception

Nom	Type	Description
`name`	`string`	Nom de l’environnement tel qu’affiché dans l’interface utilisateur.
`image_url`	`string`	URL vers le tarball qui sera téléchargé et extrait.
`default_environment`	`boolean`	Indique s’il s’agit de l’environnement par défaut fourni avec GitHub.
`download`	`object`	État de téléchargement de cet environnement.
`hooks_count`	`integer`	Nombre de hooks pré-réception qui utilisent cet environnement.

Téléchargement de l’environnement de pré-réception

Nom	Type	Description
`state`	`string`	État du téléchargement le plus récent.
`downloaded_at`	`string`	Heure à laquelle le téléchargement le plus récent a démarré.
`message`	`string`	En cas d’échec, cela contiendra tous les messages d’erreur.

Les valeurs possibles pour state sont not_started, in_progress, success et failed.

List pre-receive environments

Fine-grained access tokens for "List pre-receive environments"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Paramètres pour «List pre-receive environments »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de requête
Nom, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Par défaut: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Par défaut: `1`
`direction` string The direction to sort the results by. Par défaut: `desc` Peut être l'un des: `asc`, `desc`
`sort` string Par défaut: `created` Peut être l'un des: `created`, `updated`, `name`

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

Status code	Description
`200`	OK

Code samples for "List pre-receive environments"

Request example

get/admin/pre-receive-environments

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  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

Fine-grained access tokens for "Create a pre-receive environment"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Paramètres pour «Create a pre-receive environment »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres du corps
Nom, Type, Description
`name` string Requis The new pre-receive environment's name.
`image_url` string Requis 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"

Request example

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: 2026-03-10" \
  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

Fine-grained access tokens for "Get a pre-receive environment"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Paramètres pour «Get a pre-receive environment »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`pre_receive_environment_id` integer Requis 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"

Request example

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: 2026-03-10" \
  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.

Fine-grained access tokens for "Update a pre-receive environment"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Paramètres pour «Update a pre-receive environment »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`pre_receive_environment_id` integer Requis The unique identifier of the pre-receive environment.

Paramètres du corps
Nom, 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"

Request example

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: 2026-03-10" \
  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

Fine-grained access tokens for "Delete a pre-receive environment"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Paramètres pour «Delete a pre-receive environment »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`pre_receive_environment_id` integer Requis 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"

Request example

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: 2026-03-10" \
  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

Fine-grained access tokens for "Start a pre-receive environment download"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Paramètres pour «Start a pre-receive environment download »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`pre_receive_environment_id` integer Requis 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"

Request example

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: 2026-03-10" \
  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
}

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`pre_receive_environment_id` integer Requis 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"

Request example

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: 2026-03-10" \
  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
}