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.
Pre-receive Hooks
Use the REST API to create, list, update and delete pre-receive hooks.
About pre-receive hooks
These endpoints are only available to authenticated site administrators. Normal users will receive a 404
response.
Object attributes
Pre-receive Hook
Name | Type | Description |
---|---|---|
name | string | The name of the hook. |
script | string | The script that the hook runs. |
script_repository | object | The GitHub repository where the script is kept. |
environment | object | The pre-receive environment where the script is executed. |
enforcement | string | The state of enforcement for this hook. |
allow_downstream_configuration | boolean | Whether 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 for "List pre-receive hooks"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Query parameters |
Name, Type, Description |
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
direction string The direction to sort the results by. Default: Can be one of: |
sort string The property to sort the results by. Default: Can be one of: |
HTTP response status codes for "List pre-receive hooks"
Status code | Description |
---|---|
200 | OK |
Code samples for "List pre-receive hooks"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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
}
]
Create a pre-receive hook
Parameters for "Create a pre-receive hook"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Body parameters |
Name, Type, Description |
name string RequiredThe name of the hook. |
script string RequiredThe script that the hook runs. |
script_repository object RequiredThe GitHub repository where the script is kept. |
environment object RequiredThe pre-receive environment where the script is executed. |
enforcement string The state of enforcement for this hook. default: |
allow_downstream_configuration boolean Whether enforcement can be overridden at the org or repo level. default: |
HTTP response status codes for "Create a pre-receive hook"
Status code | Description |
---|---|
201 | Created |
Code samples for "Create a pre-receive hook"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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
}
Get a pre-receive hook
Parameters for "Get a pre-receive hook"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_hook_id integer RequiredThe unique identifier of the pre-receive hook. |
HTTP response status codes for "Get a pre-receive hook"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get a pre-receive hook"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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
}
Update a pre-receive hook
Parameters for "Update a pre-receive hook"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_hook_id integer RequiredThe unique identifier of the pre-receive hook. |
Body parameters |
Name, Type, Description |
name string The name of the hook. |
script string The script that the hook runs. |
script_repository object The GitHub repository where the script is kept. |
environment object The pre-receive environment where the script is executed. |
enforcement string The state of enforcement for this hook. |
allow_downstream_configuration boolean Whether enforcement can be overridden at the org or repo level. |
HTTP response status codes for "Update a pre-receive hook"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a pre-receive hook"
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-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
}
Delete a pre-receive hook
Parameters for "Delete a pre-receive hook"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
pre_receive_hook_id integer RequiredThe unique identifier of the pre-receive hook. |
HTTP response status codes for "Delete a pre-receive hook"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Delete a pre-receive hook"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID
Response
Status: 204