Skip to main content

This version of GitHub Enterprise was discontinued on 2022-06-03. 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.

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.

Pre-receive Hooks

The Pre-receive Hooks API allows you to create, list, update and delete pre-receive hooks.

It is only available to authenticated site administrators. Normal users will receive a 404 response if they try to access it.

Object attributes

Pre-receive Hook

NameTypeDescription
namestringThe name of the hook.
scriptstringThe script that the hook runs.
script_repositoryobjectThe GitHub repository where the script is kept.
environmentobjectThe pre-receive environment where the script is executed.
enforcementstringThe state of enforcement for this hook.
allow_downstream_configurationbooleanWhether enforcement can be overridden at the org or repo level.

Possible values for enforcement are enabled, disabled andtesting. disabled indicates the pre-receive hook will not run. enabled indicates it will run and reject any pushes that result in a non-zero status. testing means the script will run but will not cause any pushes to be rejected.

List pre-receive hooks

Parameters

Headers
Name, Type, Description
acceptstring

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

See preview notice
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

The property to sort the results by.

Default: created

Can be one of: created, updated, name

HTTP response status codes

Status codeDescription
200

OK

Code samples

get/admin/pre-receive-hooks
curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks

Response

Status: 200
[ { "id": 1, "name": "Check Commits", "enforcement": "disabled", "script": "scripts/commmit_check.sh", "script_repository": { "id": 595, "full_name": "DevIT/hooks", "url": "https://github.example.com/api/v3/repos/DevIT/hooks", "html_url": "https://github.example.com/DevIT/hooks" }, "environment": { "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 } }, "allow_downstream_configuration": false } ]

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview

Create a pre-receive hook

Parameters

Headers
Name, Type, Description
acceptstring

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

See preview notice
Body parameters
Name, Type, Description
namestringRequired

The name of the hook.

scriptstringRequired

The script that the hook runs.

script_repositoryobjectRequired

The GitHub repository where the script is kept.

environmentobjectRequired

The pre-receive environment where the script is executed.

enforcementstring

The state of enforcement for this hook. default: disabled

allow_downstream_configurationboolean

Whether enforcement can be overridden at the org or repo level. default: false

HTTP response status codes

Status codeDescription
201

Created

Code samples

post/admin/pre-receive-hooks
curl \ -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks \ -d '{"name":"Check Commits","script":"scripts/commit_check.sh","enforcement":"disabled","allow_downstream_configuration":false,"script_repository":{"full_name":"DevIT/hooks"},"environment":{"id":2}}'

Response

Status: 201
{ "id": 1, "name": "Check Commits", "enforcement": "disabled", "script": "scripts/commmit_check.sh", "script_repository": { "id": 595, "full_name": "DevIT/hooks", "url": "https://github.example.com/api/v3/repos/DevIT/hooks", "html_url": "https://github.example.com/DevIT/hooks" }, "environment": { "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 } }, "allow_downstream_configuration": false }

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview

Get a pre-receive hook

Parameters

Headers
Name, Type, Description
acceptstring

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

See preview notice
Path parameters
Name, Type, Description
pre_receive_hook_idintegerRequired

The unique identifier of the pre-receive hook.

HTTP response status codes

Status codeDescription
200

OK

Code samples

get/admin/pre-receive-hooks/{pre_receive_hook_id}
curl \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 200
{ "id": 1, "name": "Check Commits", "enforcement": "disabled", "script": "scripts/commmit_check.sh", "script_repository": { "id": 595, "full_name": "DevIT/hooks", "url": "https://github.example.com/api/v3/repos/DevIT/hooks", "html_url": "https://github.example.com/DevIT/hooks" }, "environment": { "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 } }, "allow_downstream_configuration": false }

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview

Update a pre-receive hook

Parameters

Headers
Name, Type, Description
acceptstring

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

See preview notice
Path parameters
Name, Type, Description
pre_receive_hook_idintegerRequired

The unique identifier of the pre-receive hook.

Body parameters
Name, Type, Description
namestring

The name of the hook.

scriptstring

The script that the hook runs.

script_repositoryobject

The GitHub repository where the script is kept.

environmentobject

The pre-receive environment where the script is executed.

enforcementstring

The state of enforcement for this hook.

allow_downstream_configurationboolean

Whether enforcement can be overridden at the org or repo level.

HTTP response status codes

Status codeDescription
200

OK

Code samples

patch/admin/pre-receive-hooks/{pre_receive_hook_id}
curl \ -X PATCH \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID \ -d '{"name":"Check Commits","environment":{"id":1},"allow_downstream_configuration":true}'

Response

Status: 200
{ "id": 1, "name": "Check Commits", "enforcement": "disabled", "script": "scripts/commmit_check.sh", "script_repository": { "id": 595, "full_name": "DevIT/hooks", "url": "https://github.example.com/api/v3/repos/DevIT/hooks", "html_url": "https://github.example.com/DevIT/hooks" }, "environment": { "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": 1, "download": { "url": "https://github.example.com/api/v3/admin/pre-receive-environments/1/downloads/latest", "state": "success", "downloaded_at": "2016-05-26T07:42:53-05:00", "message": null } }, "allow_downstream_configuration": true }

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview

Delete a pre-receive hook

Parameters

Headers
Name, Type, Description
acceptstring

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

See preview notice
Path parameters
Name, Type, Description
pre_receive_hook_idintegerRequired

The unique identifier of the pre-receive hook.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

delete/admin/pre-receive-hooks/{pre_receive_hook_id}
curl \ -X DELETE \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: token <TOKEN>" \ http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID

Response

Status: 204

Preview notice

APIs for managing pre-receive hooks are currently available for developers to preview. During the preview period, the APIs may change without advance notice.

To access the API you must provide a custom media type in the Accept header:

application/vnd.github.eye-scream-preview