This version of GitHub Enterprise Server was discontinued on 2024-07-09. 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 Server. For help with the upgrade, contact GitHub Enterprise support.
REST API endpoints for 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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." 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"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
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"
Name, Type, Description |
---|
accept string Setting to |
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"
Request example
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
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"
Name, Type, Description |
---|
accept string Setting to |
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"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
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"
Name, Type, Description |
---|
accept string Setting to |
Name, Type, Description |
---|
pre_receive_hook_id integer RequiredThe unique identifier of the 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. |
HTTP response status codes for "Update a pre-receive hook"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a pre-receive hook"
Request example
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
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"
Name, Type, Description |
---|
accept string Setting to |
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"
Request example
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/admin/pre-receive-hooks/PRE_RECEIVE_HOOK_ID
Response
Status: 204