Nous avons récemment déplacé une partie de la documentation de l’API REST. Si vous ne trouvez pas ce que vous recherchez, vous pouvez essayer la page d’API REST Actions.

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.

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 AE.
`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, des messages d’erreur sont générés.

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

List pre-receive environments

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). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`
`direction`string The direction to sort the results by. Default: `desc` Peut être: `asc`, `desc`
`sort`string Default: `created` Peut être: `created`, `updated`, `name`

Codes d’état de la réponse HTTP pour « List pre-receive environments »

Code d’état	Description
`200`	OK

Exemples de code pour « List pre-receive environments »

get/admin/pre-receive-environments

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  https://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

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`stringObligatoire The new pre-receive environment's name.
`image_url`stringObligatoire URL from which to download a tarball of this environment.

Codes d’état de la réponse HTTP pour « Create a pre-receive environment »

Code d’état	Description
`201`	Created

Exemples de code pour « 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>" \
  https://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

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`integerObligatoire The unique identifier of the pre-receive environment.

Codes d’état de la réponse HTTP pour « Get a pre-receive environment »

Code d’état	Description
`200`	OK

Exemples de code pour « 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>" \
  https://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.

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`integerObligatoire 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.

Codes d’état de la réponse HTTP pour « Update a pre-receive environment »

Code d’état	Description
`200`	OK
`422`	Client Errors

Exemples de code pour « 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>" \
  https://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

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`integerObligatoire The unique identifier of the pre-receive environment.

Codes d’état de la réponse HTTP pour « Delete a pre-receive environment »

Code d’état	Description
`204`	No Content
`422`	Client Errors

Exemples de code pour « 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>" \
  https://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

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`integerObligatoire The unique identifier of the pre-receive environment.

Codes d’état de la réponse HTTP pour « Start a pre-receive environment download »

Code d’état	Description
`202`	Accepted
`422`	Client Errors

Exemples de code pour « 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>" \
  https://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.

Paramètres pour « Get the download status for 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`integerObligatoire The unique identifier of the pre-receive environment.

Codes d’état de la réponse HTTP pour « Get the download status for a pre-receive environment »

Code d’état	Description
`200`	OK

Exemples de code pour « 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>" \
  https://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
}