Endpoint URLs
REST API endpoints—except Management Console API endpoints— are prefixed with the following URL:
http(s)://[hostname]/api/v3
Management Console API endpoints are only prefixed with a hostname:
http(s)://hostname/
Authentication
Your GitHub Enterprise Server installation's API endpoints accept the same authentication methods as the GitHub.com API. You can authenticate yourself with OAuth tokens (which can be created using the Authorizations API) or basic authentication.
OAuth tokens must have the site_admin
OAuth scope when used with Enterprise-specific endpoints.
Enterprise administration API endpoints are only accessible to authenticated GitHub Enterprise Server site administrators, except for the Management Console API, which requires the Management Console password.
Version information
The current version of your enterprise is returned in the response header of every API:
X-GitHub-Enterprise-Version: enterprise-server@2.22.0
You can also read the current version by calling the meta endpoint.
GitHub Actions
List self-hosted runner groups for an enterprise
Lists all self-hosted runner groups for an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runner-groups
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups', {
enterprise: 'enterprise'
})
Response
Status: 200 OK
{
"total_count": 3,
"runner_groups": [
{
"id": 1,
"name": "Default",
"visibility": "all",
"default": true,
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/1/runners",
"allows_public_repositories": false
},
{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/runners",
"allows_public_repositories": true
},
{
"id": 3,
"name": "expensive-hardware",
"visibility": "private",
"default": false,
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/3/runners",
"allows_public_repositories": true
}
]
}
Create a self-hosted runner group for an enterprise
Creates a new self-hosted runner group for an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
post /enterprises/{enterprise}/actions/runner-groups
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
name |
string | body |
Required. Name of the runner group. |
visibility |
string | body |
Visibility of a runner group. You can select all organizations or select individual organization. Can be one of: |
selected_organization_ids |
array of integers | body |
List of organization IDs that can access the runner group. |
runners |
array of integers | body |
List of runner IDs to add to the runner group. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runner-groups', {
enterprise: 'enterprise',
name: 'name'
})
Response
Status: 201 Created
{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
"allows_public_repositories": false
}
Get a self-hosted runner group for an enterprise
Gets a specific self-hosted runner group for an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
enterprise: 'enterprise',
runner_group_id: 42
})
Response
Status: 200 OK
{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
"allows_public_repositories": false
}
Update a self-hosted runner group for an enterprise
Updates the name
and visibility
of a self-hosted runner group in an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
patch /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
name |
string | body |
Name of the runner group. |
visibility |
string | body |
Visibility of a runner group. You can select all organizations or select individual organizations. Can be one of: all |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42 \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
enterprise: 'enterprise',
runner_group_id: 42,
name: 'name'
})
Response
Status: 200 OK
{
"id": 2,
"name": "Expensive hardware runners",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
"allows_public_repositories": true
}
Delete a self-hosted runner group from an enterprise
Deletes a self-hosted runner group for an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
enterprise: 'enterprise',
runner_group_id: 42
})
Response
Status: 204 No Content
List organization access to a self-hosted runner group in an enterprise
Lists the organizations with access to a self-hosted runner group.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations', {
enterprise: 'enterprise',
runner_group_id: 42
})
Response
Status: 200 OK
{
"total_count": 1,
"organizations": [
{
"login": "octocat",
"id": 161335,
"node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
"url": "https://api.github.com/orgs/octo-org",
"repos_url": "https://api.github.com/orgs/octo-org/repos",
"events_url": "https://api.github.com/orgs/octo-org/events",
"hooks_url": "https://api.github.com/orgs/octo-org/hooks",
"issues_url": "https://api.github.com/orgs/octo-org/issues",
"members_url": "https://api.github.com/orgs/octo-org/members{/member}",
"public_members_url": "https://api.github.com/orgs/octo-org/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
}
]
}
Set organization access for a self-hosted runner group in an enterprise
Replaces the list of organizations that have access to a self-hosted runner configured in an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
selected_organization_ids |
array of integers | body |
Required. List of organization IDs that can access the runner group. |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations \
-d '{"selected_organization_ids":[42]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations', {
enterprise: 'enterprise',
runner_group_id: 42,
selected_organization_ids: [
42
]
})
Response
Status: 204 No Content
Add organization access to a self-hosted runner group in an enterprise
Adds an organization to the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility
set to selected
. For more information, see "Create a self-hosted runner group for an enterprise."
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
org_id |
integer | path |
Unique identifier of an organization. |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations/42
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}', {
enterprise: 'enterprise',
runner_group_id: 42,
org_id: 42
})
Response
Status: 204 No Content
Remove organization access to a self-hosted runner group in an enterprise
Removes an organization from the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility
set to selected
. For more information, see "Create a self-hosted runner group for an enterprise."
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
org_id |
integer | path |
Unique identifier of an organization. |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/organizations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}', {
enterprise: 'enterprise',
runner_group_id: 42,
org_id: 42
})
Response
Status: 204 No Content
List self-hosted runners in a group for an enterprise
Lists the self-hosted runners that are in a specific enterprise group.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners', {
enterprise: 'enterprise',
runner_group_id: 42
})
Response
Status: 200 OK
{
"total_count": 2,
"runners": [
{
"id": 23,
"name": "linux_runner",
"os": "linux",
"status": "online",
"busy": true
},
{
"id": 24,
"name": "mac_runner",
"os": "macos",
"status": "offline",
"busy": false
}
]
}
Set self-hosted runners in a group for an enterprise
Replaces the list of self-hosted runners that are part of an enterprise runner group.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
runners |
array of integers | body |
Required. List of runner IDs to add to the runner group. |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners \
-d '{"runners":[42]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners', {
enterprise: 'enterprise',
runner_group_id: 42,
runners: [
42
]
})
Response
Status: 204 No Content
Add a self-hosted runner to a group for an enterprise
Adds a self-hosted runner to a runner group configured in an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
runner_id |
integer | path |
Unique identifier of the self-hosted runner. |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners/42
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}', {
enterprise: 'enterprise',
runner_group_id: 42,
runner_id: 42
})
Response
Status: 204 No Content
Remove a self-hosted runner from a group for an enterprise
Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id |
integer | path |
Unique identifier of the self-hosted runner group. |
runner_id |
integer | path |
Unique identifier of the self-hosted runner. |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runner-groups/42/runners/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}', {
enterprise: 'enterprise',
runner_group_id: 42,
runner_id: 42
})
Response
Status: 204 No Content
List self-hosted runners for an enterprise
Lists all self-hosted runners configured for an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runners
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners', {
enterprise: 'enterprise'
})
Response
Status: 200 OK
{
"total_count": 2,
"runners": [
{
"id": 23,
"name": "linux_runner",
"os": "linux",
"status": "online",
"busy": true
},
{
"id": 24,
"name": "mac_runner",
"os": "macos",
"status": "offline",
"busy": false
}
]
}
List runner applications for an enterprise
Lists binaries for the runner application that you can download and run.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runners/downloads
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/downloads
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners/downloads', {
enterprise: 'enterprise'
})
Response
Status: 200 OK
[
{
"os": "osx",
"architecture": "x64",
"download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-osx-x64-2.164.0.tar.gz",
"filename": "actions-runner-osx-x64-2.164.0.tar.gz"
},
{
"os": "linux",
"architecture": "x64",
"download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-x64-2.164.0.tar.gz",
"filename": "actions-runner-linux-x64-2.164.0.tar.gz"
},
{
"os": "linux",
"architecture": "arm",
"download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm-2.164.0.tar.gz",
"filename": "actions-runner-linux-arm-2.164.0.tar.gz"
},
{
"os": "win",
"architecture": "x64",
"download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-win-x64-2.164.0.zip",
"filename": "actions-runner-win-x64-2.164.0.zip"
},
{
"os": "linux",
"architecture": "arm64",
"download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm64-2.164.0.tar.gz",
"filename": "actions-runner-linux-arm64-2.164.0.tar.gz"
}
]
Create a registration token for an enterprise
Returns a token that you can pass to the config
script. The token expires after one hour.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
Example using registration token
Configure your self-hosted runner, replacing TOKEN
with the registration token provided by this endpoint.
./config.sh --url https://github.com/enterprises/octo-enterprise --token TOKEN
post /enterprises/{enterprise}/actions/runners/registration-token
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/registration-token
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runners/registration-token', {
enterprise: 'enterprise'
})
Response
Status: 201 Created
{
"token": "LLBF3JGZDX3P5PMEXLND6TS6FCWO6",
"expires_at": "2020-01-22T12:13:35.123-08:00"
}
Create a remove token for an enterprise
Returns a token that you can pass to the config
script to remove a self-hosted runner from an enterprise. The token expires after one hour.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
Example using remove token
To remove your self-hosted runner from an enterprise, replace TOKEN
with the remove token provided by this
endpoint.
./config.sh remove --token TOKEN
post /enterprises/{enterprise}/actions/runners/remove-token
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/remove-token
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runners/remove-token', {
enterprise: 'enterprise'
})
Response
Status: 201 Created
{
"token": "AABF3JGZDX3P5PMEXLND6TS6FCWO6",
"expires_at": "2020-01-29T12:13:35.123-08:00"
}
Get a self-hosted runner for an enterprise
Gets a specific self-hosted runner configured in an enterprise.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
get /enterprises/{enterprise}/actions/runners/{runner_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_id |
integer | path |
Unique identifier of the self-hosted runner. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/42
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners/{runner_id}', {
enterprise: 'enterprise',
runner_id: 42
})
Response
Status: 200 OK
{
"id": 23,
"name": "mac_runner",
"os": "macos",
"status": "online",
"busy": true
}
Delete a self-hosted runner from an enterprise
Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.
You must authenticate using an access token with the admin:enterprise
scope to use this endpoint.
delete /enterprises/{enterprise}/actions/runners/{runner_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
enterprise |
string | path |
The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_id |
integer | path |
Unique identifier of the self-hosted runner. |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprises/ENTERPRISE/actions/runners/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runners/{runner_id}', {
enterprise: 'enterprise',
runner_id: 42
})
Response
Status: 204 No Content
Admin stats
The Admin Stats API provides a variety of metrics about your installation. It is only available to authenticated site administrators. Normal users will receive a 404
response if they try to access it.
get /enterprise/stats/all
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/all
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/all')
Response
Status: 200 OK
{
"repos": {
"total_repos": 212,
"root_repos": 194,
"fork_repos": 18,
"org_repos": 51,
"total_pushes": 3082,
"total_wikis": 15
},
"hooks": {
"total_hooks": 27,
"active_hooks": 23,
"inactive_hooks": 4
},
"pages": {
"total_pages": 36
},
"orgs": {
"total_orgs": 33,
"disabled_orgs": 0,
"total_teams": 60,
"total_team_members": 314
},
"users": {
"total_users": 254,
"admin_users": 45,
"suspended_users": 21
},
"pulls": {
"total_pulls": 86,
"merged_pulls": 60,
"mergeable_pulls": 21,
"unmergeable_pulls": 3
},
"issues": {
"total_issues": 179,
"open_issues": 83,
"closed_issues": 96
},
"milestones": {
"total_milestones": 7,
"open_milestones": 6,
"closed_milestones": 1
},
"gists": {
"total_gists": 178,
"private_gists": 151,
"public_gists": 25
},
"comments": {
"total_commit_comments": 6,
"total_gist_comments": 28,
"total_issue_comments": 366,
"total_pull_request_comments": 30
}
}
get /enterprise/stats/comments
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/comments
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/comments')
Response
Status: 200 OK
get /enterprise/stats/gists
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/gists
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/gists')
Response
Status: 200 OK
get /enterprise/stats/hooks
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/hooks')
Response
Status: 200 OK
get /enterprise/stats/issues
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/issues
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/issues')
Response
Status: 200 OK
get /enterprise/stats/milestones
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/milestones
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/milestones')
Response
Status: 200 OK
get /enterprise/stats/orgs
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/orgs
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/orgs')
Response
Status: 200 OK
get /enterprise/stats/pages
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/pages
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/pages')
Response
Status: 200 OK
get /enterprise/stats/pulls
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/pulls
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/pulls')
Response
Status: 200 OK
get /enterprise/stats/repos
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/repos
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/repos')
Response
Status: 200 OK
get /enterprise/stats/users
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/stats/users
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/stats/users')
Response
Status: 200 OK
Global webhooks
Global webhooks are installed on your enterprise. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your enterprise. Global webhooks can subscribe to the organization, user, repository, team, member, membership, fork, and ping event types.
This API is only available to authenticated site administrators. Normal users will receive a 404
response if they try to access it. To learn how to configure global webhooks, see About global webhooks.
get /admin/hooks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
accept |
string | header |
This API is under preview and subject to change. Default:application/vnd.github.superpro-preview+json |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.superpro-preview+json" \
http(s)://{hostname}/api/v3/admin/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks', {
mediaType: {
previews: [
'superpro'
]
}
})
Response
Status: 200 OK
[
{
"type": "Global",
"id": 1,
"name": "web",
"active": true,
"events": [
"organization",
"user"
],
"config": {
"url": "https://example.com",
"content_type": "json",
"insecure_ssl": "0",
"secret": "********"
},
"updated_at": "2017-12-07T00:14:59Z",
"created_at": "2017-12-07T00:14:59Z",
"url": "https://api.github.com/admin/hooks/1",
"ping_url": "https://api.github.com/admin/hooks/1/pings"
}
]
Preview notice
The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.superpro-preview+json
☝️This header is required.post /admin/hooks
Parameters
Name | Type | In | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
||||||||
accept |
string | header |
This API is under preview and subject to change. Default:application/vnd.github.superpro-preview+json |
||||||||
name |
string | body |
Required. Must be passed as "web". |
||||||||
config |
object | body |
Required. Key/value pairs to provide settings for this webhook. |
||||||||
Properties of the
|
url (string)
|
Required. The URL to which the payloads will be delivered. |
content_type (string)
|
The media type used to serialize the payloads. Supported values include |
secret (string)
|
If provided, the |
insecure_ssl (string)
|
Determines whether the SSL certificate of the host for |
events
The events that trigger this webhook. A global webhook can be triggered by user
and organization
events. Default: user
and organization
.
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.superpro-preview+json" \
http(s)://{hostname}/api/v3/admin/hooks \
-d '{"name":"name","config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks', {
name: 'name',
config: {
url: 'url',
content_type: 'content_type',
secret: 'secret',
insecure_ssl: 'insecure_ssl'
},
mediaType: {
previews: [
'superpro'
]
}
})
Response
Status: 201 Created
{
"type": "Global",
"id": 1,
"name": "web",
"active": true,
"events": [
"organization",
"user"
],
"config": {
"url": "https://example.com",
"content_type": "json",
"insecure_ssl": "0",
"secret": "********"
},
"updated_at": "2017-12-07T00:14:59Z",
"created_at": "2017-12-07T00:14:59Z",
"url": "https://api.github.com/admin/hooks/1",
"ping_url": "https://api.github.com/admin/hooks/1/pings"
}
Preview notice
The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.superpro-preview+json
☝️This header is required.get /admin/hooks/{hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
accept |
string | header |
This API is under preview and subject to change. Default:application/vnd.github.superpro-preview+json |
hook_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.superpro-preview+json" \
http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/hooks/{hook_id}', {
hook_id: 42,
mediaType: {
previews: [
'superpro'
]
}
})
Response
Status: 200 OK
{
"type": "Global",
"id": 1,
"name": "web",
"active": true,
"events": [
"organization",
"user"
],
"config": {
"url": "https://example.com",
"content_type": "json",
"insecure_ssl": "0",
"secret": "********"
},
"updated_at": "2017-12-07T00:14:59Z",
"created_at": "2017-12-07T00:14:59Z",
"url": "https://api.github.com/admin/hooks/1",
"ping_url": "https://api.github.com/admin/hooks/1/pings"
}
Preview notice
The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.superpro-preview+json
☝️This header is required.Update a global webhook
Parameters that are not provided will be overwritten with the default value or removed if no default exists.
patch /admin/hooks/{hook_id}
Parameters
Name | Type | In | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
||||||||
accept |
string | header |
This API is under preview and subject to change. Default:application/vnd.github.superpro-preview+json |
||||||||
hook_id |
integer | path | |||||||||
config |
object | body |
Key/value pairs to provide settings for this webhook. |
||||||||
Properties of the
|
url (string)
|
Required. The URL to which the payloads will be delivered. |
content_type (string)
|
The media type used to serialize the payloads. Supported values include |
secret (string)
|
If provided, the |
insecure_ssl (string)
|
Determines whether the SSL certificate of the host for |
events
The events that trigger this webhook. A global webhook can be triggered by user
and organization
events. Default: user
and organization
.
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.superpro-preview+json" \
http(s)://{hostname}/api/v3/admin/hooks/42 \
-d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/hooks/{hook_id}', {
hook_id: 42,
config: {
url: 'url',
content_type: 'content_type',
secret: 'secret',
insecure_ssl: 'insecure_ssl'
},
mediaType: {
previews: [
'superpro'
]
}
})
Response
Status: 200 OK
{
"type": "Global",
"id": 1,
"name": "web",
"active": true,
"events": [
"organization"
],
"config": {
"url": "https://example.com",
"content_type": "form",
"insecure_ssl": "0"
},
"updated_at": "2017-12-07T00:14:59Z",
"created_at": "2017-12-07T00:14:59Z",
"url": "https://api.github.com/admin/hooks/1",
"ping_url": "https://api.github.com/admin/hooks/1/pings"
}
Preview notice
The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.superpro-preview+json
☝️This header is required.delete /admin/hooks/{hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
accept |
string | header |
This API is under preview and subject to change. Default:application/vnd.github.superpro-preview+json |
hook_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.superpro-preview+json" \
http(s)://{hostname}/api/v3/admin/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/hooks/{hook_id}', {
hook_id: 42,
mediaType: {
previews: [
'superpro'
]
}
})
Response
Status: 204 No Content
Preview notice
The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.superpro-preview+json
☝️This header is required.Ping a global webhook
This will trigger a ping event to be sent to the webhook.
post /admin/hooks/{hook_id}/pings
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
accept |
string | header |
This API is under preview and subject to change. Default:application/vnd.github.superpro-preview+json |
hook_id |
integer | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.superpro-preview+json" \
http(s)://{hostname}/api/v3/admin/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/hooks/{hook_id}/pings', {
hook_id: 42,
mediaType: {
previews: [
'superpro'
]
}
})
Response
Status: 204 No Content
Preview notice
The Global Webhooks API is currently available for developers to preview. To access the API during the preview period, you must provide a custom media type in the Accept
header:
application/vnd.github.superpro-preview+json
☝️This header is required.LDAP
You can use the LDAP API to update account relationships between a GitHub Enterprise Server user or team and its linked LDAP entry or queue a new synchronization.
With the LDAP mapping endpoints, you're able to update the Distinguished Name (DN) that a user or team maps to. Note that the LDAP endpoints are generally only effective if your GitHub Enterprise Server appliance has LDAP Sync enabled. The Update LDAP mapping for a user endpoint can be used when LDAP is enabled, even if LDAP Sync is disabled.
Update LDAP mapping for a team
Updates the distinguished name (DN) of the LDAP entry to map to a team. LDAP synchronization must be enabled to map LDAP entries to a team. Use the Create a team endpoint to create a team with LDAP mapping.
If you pass the hellcat-preview
media type, you can also update the LDAP mapping of a child team.
patch /admin/ldap/teams/{team_id}/mapping
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
team_id |
integer | path | |
ldap_dn |
string | body |
Required. The distinguished name (DN) of the LDAP entry to map to a team. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/ldap/teams/42/mapping \
-d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/teams/{team_id}/mapping', {
team_id: 42,
ldap_dn: 'ldap_dn'
})
Response
Status: 200 OK
{
"ldap_dn": "cn=Enterprise Ops,ou=teams,dc=github,dc=com",
"id": 1,
"node_id": "MDQ6VGVhbTE=",
"url": "https://api.github.com/teams/1",
"html_url": "https://github.com/orgs/github/teams/justice-league",
"name": "Justice League",
"slug": "justice-league",
"description": "A great team.",
"privacy": "closed",
"permission": "admin",
"members_url": "https://api.github.com/teams/1/members{/member}",
"repositories_url": "https://api.github.com/teams/1/repos",
"parent": null
}
Preview notice
The Nested Teams API is currently available for developers to preview. See the blog post for full details. To access the API, you must provide a custom media type in the Accept
header:
application/vnd.github.hellcat-preview+json
Sync LDAP mapping for a team
Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201
is returned, the sync job is queued successfully, and is performed when the instance is ready.
post /admin/ldap/teams/{team_id}/sync
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
team_id |
integer | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/ldap/teams/42/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/teams/{team_id}/sync', {
team_id: 42
})
Response
Status: 201 Created
{
"status": "queued"
}
patch /admin/ldap/users/{username}/mapping
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path | |
ldap_dn |
string | body |
Required. The distinguished name (DN) of the LDAP entry to map to a team. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/mapping \
-d '{"ldap_dn":"ldap_dn"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/ldap/users/{username}/mapping', {
username: 'username',
ldap_dn: 'ldap_dn'
})
Response
Status: 200 OK
{
"ldap_dn": "uid=asdf,ou=users,dc=github,dc=com",
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false,
"name": "monalisa octocat",
"company": "GitHub",
"blog": "https://github.com/blog",
"location": "San Francisco",
"email": "octocat@github.com",
"hireable": false,
"bio": "There once was...",
"twitter_username": "monatheoctocat",
"public_repos": 2,
"public_gists": 1,
"followers": 20,
"following": 0,
"created_at": "2008-01-14T04:33:35Z",
"updated_at": "2008-01-14T04:33:35Z",
"private_gists": 81,
"total_private_repos": 100,
"owned_private_repos": 100,
"disk_usage": 10000,
"collaborators": 8,
"two_factor_authentication": true,
"plan": {
"name": "Medium",
"space": 400,
"private_repos": 20,
"collaborators": 0
}
}
Sync LDAP mapping for a user
Note that this API call does not automatically initiate an LDAP sync. Rather, if a 201
is returned, the sync job is queued successfully, and is performed when the instance is ready.
post /admin/ldap/users/{username}/sync
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/ldap/users/USERNAME/sync
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/ldap/users/{username}/sync', {
username: 'username'
})
Response
Status: 201 Created
{
"status": "queued"
}
License
The License API provides information on your Enterprise license. It is only available to authenticated site administrators. Normal users will receive a 404
response if they try to access it.
get /enterprise/settings/license
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/enterprise/settings/license
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprise/settings/license')
Response
Status: 200 OK
{
"seats": 1400,
"seats_used": 1316,
"seats_available": 84,
"kind": "standard",
"days_until_expiration": 365,
"expire_at": "2016/02/06 12:41:52 -0600"
}
Management console
The Management Console API helps you manage your GitHub Enterprise Server installation.
You must explicitly set the port number when making API calls to the Management Console. If TLS is enabled on your enterprise, the port number is 8443
; otherwise, the port number is 8080
.
If you don't want to provide a port number, you'll need to configure your tool to automatically follow redirects.
You may also need to add the -k
flag when using curl
, since GitHub Enterprise Server uses a self-signed certificate before you add your own TLS certificate.
Authentication
You need to pass your Management Console password as an authentication token to every Management Console API endpoint except /setup/api/start
.
Use the api_key
parameter to send this token with each request. For example:
$ curl -L 'https://hostname:admin_port/setup/api?api_key=your-amazing-password'
You can also use standard HTTP authentication to send this token. For example:
$ curl -L 'https://api_key:your-amazing-password@hostname:admin_port/setup/api'
Get the configuration status
This endpoint allows you to check the status of the most recent configuration process:
Note that you may need to wait several seconds after you start a process before you can check its status.
The different statuses are:
Status | Description |
---|---|
PENDING | The job has not started yet |
CONFIGURING | The job is running |
DONE | The job has finished correctly |
FAILED | The job has finished unexpectedly |
get /setup/api/configcheck
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/configcheck
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/configcheck')
Response
Status: 200 OK
{
"status": "running",
"progress": [
{
"status": "DONE",
"key": "Appliance core components"
},
{
"status": "DONE",
"key": "GitHub utilities"
},
{
"status": "DONE",
"key": "GitHub applications"
},
{
"status": "CONFIGURING",
"key": "GitHub services"
},
{
"status": "PENDING",
"key": "Reloading appliance services"
}
]
}
Start a configuration process
This endpoint allows you to start a configuration process at any time for your updated settings to take effect:
post /setup/api/configure
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/configure
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/configure')
Response
Status: 202 Accepted
get /setup/api/maintenance
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/maintenance
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/maintenance')
Response
Status: 200 OK
{
"status": "scheduled",
"scheduled_time": "Tuesday, January 22 at 15:34 -0800",
"connection_services": [
{
"name": "git operations",
"number": 0
},
{
"name": "mysql queries",
"number": 233
},
{
"name": "resque jobs",
"number": 54
}
]
}
Enable or disable maintenance mode
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
post /setup/api/maintenance
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
maintenance |
string | body |
Required. A JSON string with the attributes The possible values for The possible values for |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/maintenance \
--data-urlencode maintenance=maintenance
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/maintenance', {
maintenance: 'maintenance'
})
Response
Status: 200 OK
{
"status": "scheduled",
"scheduled_time": "Tuesday, January 22 at 15:34 -0800",
"connection_services": [
{
"name": "git operations",
"number": 0
},
{
"name": "mysql queries",
"number": 233
},
{
"name": "resque jobs",
"number": 54
}
]
}
get /setup/api/settings
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/settings
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings')
Response
Status: 200 OK
{
"enterprise": {
"private_mode": false,
"public_pages": false,
"subdomain_isolation": true,
"signup_enabled": false,
"github_hostname": "ghe.local",
"identicons_host": "dotcom",
"http_proxy": null,
"auth_mode": "default",
"expire_sessions": false,
"admin_password": null,
"configuration_id": 1401777404,
"configuration_run_count": 4,
"avatar": {
"enabled": false,
"uri": ""
},
"customer": {
"name": "GitHub",
"email": "stannis@themannis.biz",
"uuid": "af6cac80-e4e1-012e-d822-1231380e52e9",
"secret_key_data": "-----BEGIN PGP PRIVATE KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nlQcYBE5TCgsBEACk4yHpUcapplebaumBMXYMiLF+nCQ0lxpx...\n-----END PGP PRIVATE KEY BLOCK-----\n",
"public_key_data": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1.4.10 (GNU/Linux)\n\nmI0ETqzZYgEEALSe6snowdenXyqvLfSQ34HWD6C7....\n-----END PGP PUBLIC KEY BLOCK-----\n"
},
"license": {
"seats": 0,
"evaluation": false,
"perpetual": false,
"unlimited_seating": true,
"support_key": "ssh-rsa AAAAB3N....",
"ssh_allowed": true,
"cluster_support": false,
"expire_at": "2016-04-27T00:00:00-07:00"
},
"github_ssl": {
"enabled": false,
"cert": null,
"key": null
},
"ldap": {
"host": null,
"port": 0,
"base": [],
"uid": null,
"bind_dn": null,
"password": null,
"method": "Plain",
"search_strategy": "detect",
"user_groups": [],
"admin_group": null,
"virtual_attribute_enabled": false,
"recursive_group_search": false,
"posix_support": true,
"user_sync_emails": false,
"user_sync_keys": false,
"user_sync_interval": 4,
"team_sync_interval": 4,
"sync_enabled": false,
"reconciliation": {
"user": null,
"org": null
},
"profile": {
"uid": "uid",
"name": null,
"mail": null,
"key": null
}
},
"cas": {
"url": null
},
"saml": {
"sso_url": null,
"certificate": null,
"certificate_path": null,
"issuer": null,
"idp_initiated_sso": false,
"disable_admin_demote": false
},
"github_oauth": {
"client_id": "12313412",
"client_secret": "kj123131132",
"organization_name": "Homestar Runners",
"organization_team": "homestarrunners/characters"
},
"smtp": {
"enabled": true,
"address": "smtp.example.com",
"authentication": "plain",
"port": "1234",
"domain": "blah",
"username": "foo",
"user_name": "mr_foo",
"enable_starttls_auto": true,
"password": "bar",
"discard-to-noreply-address": true,
"support_address": "enterprise@github.com",
"support_address_type": "email",
"noreply_address": "noreply@github.com"
},
"ntp": {
"primary_server": "0.pool.ntp.org",
"secondary_server": "1.pool.ntp.org"
},
"timezone": null,
"snmp": {
"enabled": false,
"community": ""
},
"syslog": {
"enabled": false,
"server": null,
"protocol_name": "udp"
},
"assets": null,
"pages": {
"enabled": true
},
"collectd": {
"enabled": false,
"server": null,
"port": 0,
"encryption": null,
"username": null,
"password": null
},
"mapping": {
"enabled": true,
"tileserver": null,
"basemap": "company.map-qsz2zrvs",
"token": null
},
"load_balancer": null
},
"run_list": [
"recipe[enterprise-configure]"
]
}
Set settings
For a list of the available settings, see the Get settings endpoint.
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
put /setup/api/settings
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
settings |
string | body |
Required. A JSON string with the new settings. Note that you only need to pass the specific settings you want to modify. For a list of the available settings, see the Get settings endpoint. |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/settings \
--data-urlencode settings=settings
JavaScript (@octokit/core.js)
await octokit.request('PUT /setup/api/settings', {
settings: 'settings'
})
Response
Status: 204 No Content
get /setup/api/settings/authorized-keys
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys
JavaScript (@octokit/core.js)
await octokit.request('GET /setup/api/settings/authorized-keys')
Response
Status: 200 OK
[
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
}
]
Add an authorized SSH key
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
post /setup/api/settings/authorized-keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
authorized_key |
string | body |
Required. The public SSH key. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
--data-urlencode authorized_key=authorized_key
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/settings/authorized-keys', {
authorized_key: 'authorized_key'
})
Response
Status: 201 Created
[
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
}
]
Remove an authorized SSH key
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
delete /setup/api/settings/authorized-keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
authorized_key |
string | body |
Required. The public SSH key. |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/settings/authorized-keys \
--data-urlencode authorized_key=authorized_key
JavaScript (@octokit/core.js)
await octokit.request('DELETE /setup/api/settings/authorized-keys', {
authorized_key: 'authorized_key'
})
Response
Status: 200 OK
[
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
},
{
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAAB...",
"pretty-print": "ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64"
}
]
Create a GitHub license
When you boot a GitHub instance for the first time, you can use the following endpoint to upload a license.
Note that you need to POST
to /setup/api/configure
to start the actual configuration process.
When using this endpoint, your GitHub instance must have a password set. This can be accomplished two ways:
- If you're working directly with the API before accessing the web interface, you must pass in the password parameter to set your password.
- If you set up your instance via the web interface before accessing the API, your calls to this endpoint do not need the password parameter.
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
post /setup/api/start
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
license |
string | body |
Required. The content of your .ghl license file. |
password |
string | body |
You must provide a password only if you are uploading your license for the first time. If you previously set a password through the web interface, you don't need this parameter. |
settings |
string | body |
An optional JSON string containing the installation settings. For a list of the available settings, see the Get settings endpoint. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/start \
--data-urlencode license=license
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/start', {
license: 'license'
})
Response
Status: 202 Accepted
Upgrade a license
This API upgrades your license and also triggers the configuration process.
Note: The request body for this operation must be submitted as application/x-www-form-urlencoded
data. You can submit a parameter value as a string, or you can use a tool such as curl
to submit a parameter value as the contents of a text file. For more information, see the curl
documentation.
post /setup/api/upgrade
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
license |
string | body |
The content of your new .ghl license file. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/setup/api/upgrade \
--data-urlencode license=license
JavaScript (@octokit/core.js)
await octokit.request('POST /setup/api/upgrade', {
license: 'license'
})
Response
Status: 202 Accepted
Organizations
The Organization Administration API allows you to create organizations on your enterprise. It is only available to authenticated site administrators. Normal users will receive a 404
response if they try to access it.
post /admin/organizations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
login |
string | body |
Required. The organization's username. |
admin |
string | body |
Required. The login of the user who will manage this organization. |
profile_name |
string | body |
The organization's display name. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/organizations \
-d '{"login":"login","admin":"admin"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/organizations', {
login: 'login',
admin: 'admin'
})
Response
Status: 201 Created
{
"login": "github",
"id": 1,
"node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
"url": "https://api.github.com/orgs/github",
"repos_url": "https://api.github.com/orgs/github/repos",
"events_url": "https://api.github.com/orgs/github/events",
"hooks_url": "https://api.github.com/orgs/github/hooks",
"issues_url": "https://api.github.com/orgs/github/issues",
"members_url": "https://api.github.com/orgs/github/members{/member}",
"public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"description": "A great organization"
}
patch /admin/organizations/{org}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
org |
string | path | |
login |
string | body |
Required. The organization's new name. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/organizations/ORG \
-d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/organizations/{org}', {
org: 'org',
login: 'login'
})
Response
Status: 202 Accepted
{
"message": "Job queued to rename organization. It may take a few minutes to complete.",
"url": "https://<hostname>/api/v3/organizations/1"
}
Organization pre-receive hooks
The Organization Pre-receive Hooks API allows you to view and modify enforcement of the pre-receive hooks that are available to an organization.
Object attributes
Name | Type | Description |
---|---|---|
name | string | The name of the hook. |
enforcement | string | The state of enforcement for the hook on this repository. |
allow_downstream_configuration | boolean | Whether repositories can override enforcement. |
configuration_url | string | URL for the endpoint where enforcement is set. |
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.
configuration_url
may be a link to this endpoint or this hook's global
configuration. Only site admins are able to access the global configuration.
List pre-receive hooks for an organization
List all pre-receive hooks that are enabled or testing for this organization as well as any disabled hooks that can be configured at the organization level. Globally disabled pre-receive hooks that do not allow downstream configuration are not listed.
get /orgs/{org}/pre-receive-hooks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
org |
string | path | |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
direction |
string | query |
One of desc |
sort |
string | query |
The sort order for the response collection. Default:created |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks', {
org: 'org',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
[
{
"id": 42,
"name": "Check Commits",
"enforcement": "disabled",
"configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
"allow_downstream_configuration": true
}
]
Notes
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
☝️This header is required.get /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
org |
string | path | |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
org: 'org',
pre_receive_hook_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"id": 42,
"name": "Check Commits",
"enforcement": "disabled",
"configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
"allow_downstream_configuration": true
}
Notes
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
☝️This header is required.Update pre-receive hook enforcement for an organization
For pre-receive hooks which are allowed to be configured at the org level, you can set enforcement
and allow_downstream_configuration
patch /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
org |
string | path | |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
enforcement |
string | body |
The state of enforcement for the hook on this repository. |
allow_downstream_configuration |
boolean | body |
Whether repositories can override enforcement. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42 \
-d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
org: 'org',
pre_receive_hook_id: 42,
enforcement: 'enforcement',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"id": 42,
"name": "Check Commits",
"enforcement": "enabled",
"configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42",
"allow_downstream_configuration": false
}
Notes
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
☝️This header is required.Remove pre-receive hook enforcement for an organization
Removes any overrides for this hook at the org level for this org.
delete /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
org |
string | path | |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/orgs/ORG/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /orgs/{org}/pre-receive-hooks/{pre_receive_hook_id}', {
org: 'org',
pre_receive_hook_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"id": 42,
"name": "Check Commits",
"enforcement": "disabled",
"configuration_url": "https://github.example.com/api/v3/admin/pre-receive-hooks/42",
"allow_downstream_configuration": true
}
Notes
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
☝️This header is required.Pre-receive environments
The Pre-receive Environments API allows you to create, list, update and delete environments for 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 Environment
Name | Type | Description |
---|---|---|
name | string | The name of the environment as displayed in the UI. |
image_url | string | URL to the tarball that will be downloaded and extracted. |
default_environment | boolean | Whether this is the default environment that ships with GitHub Enterprise Server. |
download | object | This environment's download status. |
hooks_count | integer | The number of pre-receive hooks that use this environment. |
Pre-receive Environment Download
Name | Type | Description |
---|---|---|
state | string | The state of the most recent download. |
downloaded_at | string | The time when the most recent download started. |
message | string | On failure, this will have any error messages produced. |
Possible values for state
are not_started
, in_progress
, success
, failed
.
get /admin/pre-receive-environments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
direction |
string | query |
One of desc |
sort |
string | query |
Default: created |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments', {
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
[
{
"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
}
}
]
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
☝️This header is required.post /admin/pre-receive-environments
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
name |
string | body |
Required. The new pre-receive environment's name. |
image_url |
string | body |
Required. URL from which to download a tarball of this environment. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments \
-d '{"name":"name","image_url":"image_url"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments', {
name: 'name',
image_url: 'image_url',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 201 Created
{
"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
}
}
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
☝️This header is required.get /admin/pre-receive-environments/{pre_receive_environment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_environment_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}', {
pre_receive_environment_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"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
}
}
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
☝️This header is required.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.
patch /admin/pre-receive-environments/{pre_receive_environment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_environment_id |
integer | path | |
name |
string | body |
This pre-receive environment's new name. |
image_url |
string | body |
URL from which to download a tarball of this environment. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments/42 \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-environments/{pre_receive_environment_id}', {
pre_receive_environment_id: 42,
name: 'name',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"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
}
}
Client Errors
Status: 422 Unprocessable Entity
{
"message": "Validation Failed",
"errors": [
{
"resource": "PreReceiveEnvironment",
"code": "custom",
"message": "Cannot modify or delete the default environment"
}
]
}
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
☝️This header is required.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
delete /admin/pre-receive-environments/{pre_receive_environment_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_environment_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-environments/{pre_receive_environment_id}', {
pre_receive_environment_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 204 No Content
Client Errors
Status: 422 Unprocessable Entity
{
"message": "Validation Failed",
"errors": [
{
"resource": "PreReceiveEnvironment",
"code": "custom",
"message": "Cannot modify or delete the default environment"
}
]
}
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
☝️This header is required.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
post /admin/pre-receive-environments/{pre_receive_environment_id}/downloads
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_environment_id |
integer | path |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-environments/{pre_receive_environment_id}/downloads', {
pre_receive_environment_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 202 Accepted
{
"url": "https://github.example.com/api/v3/admin/pre-receive-environments/3/downloads/latest",
"state": "not_started",
"downloaded_at": null,
"message": null
}
Client Errors
Status: 422 Unprocessable Entity
{
"message": "Validation Failed",
"errors": [
{
"resource": "PreReceiveEnvironment",
"code": "custom",
"message": "Can not start a new download when a download is in progress"
}
]
}
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
☝️This header is required.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.
get /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_environment_id |
integer | path |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-environments/42/downloads/latest
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-environments/{pre_receive_environment_id}/downloads/latest', {
pre_receive_environment_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"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
}
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
☝️This header is required.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
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.
get /admin/pre-receive-hooks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
direction |
string | query |
One of desc |
sort |
string | query |
One of created |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks', {
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
[
{
"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
☝️This header is required.post /admin/pre-receive-hooks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
name |
string | body |
Required. The name of the hook. |
script |
string | body |
Required. The script that the hook runs. |
script_repository |
object | body |
Required. The GitHub repository where the script is kept. |
environment |
object | body |
Required. The pre-receive environment where the script is executed. |
enforcement |
string | body |
The state of enforcement for this hook. default: |
allow_downstream_configuration |
boolean | body |
Whether enforcement can be overridden at the org or repo level. default: |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-hooks \
-d '{"name":"name","script":"script","script_repository":{},"environment":{}}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/pre-receive-hooks', {
name: 'name',
script: 'script',
script_repository: {},
environment: {},
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 201 Created
{
"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
☝️This header is required.get /admin/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/pre-receive-hooks/{pre_receive_hook_id}', {
pre_receive_hook_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"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
☝️This header is required.patch /admin/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
name |
string | body |
The name of the hook. |
script |
string | body |
The script that the hook runs. |
script_repository |
object | body |
The GitHub repository where the script is kept. |
environment |
object | body |
The pre-receive environment where the script is executed. |
enforcement |
string | body |
The state of enforcement for this hook. |
allow_downstream_configuration |
boolean | body |
Whether enforcement can be overridden at the org or repo level. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42 \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/pre-receive-hooks/{pre_receive_hook_id}', {
pre_receive_hook_id: 42,
name: 'name',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"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
☝️This header is required.delete /admin/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/admin/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/pre-receive-hooks/{pre_receive_hook_id}', {
pre_receive_hook_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 204 No Content
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
☝️This header is required.Repository pre-receive hooks
The Repository Pre-receive Hooks API allows you to view and modify enforcement of the pre-receive hooks that are available to a repository.
Object attributes
Name | Type | Description |
---|---|---|
name | string | The name of the hook. |
enforcement | string | The state of enforcement for the hook on this repository. |
configuration_url | string | URL for the endpoint where enforcement is set. |
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.
configuration_url
may be a link to this repository, it's organization owner or global configuration. Authorization to access the endpoint at configuration_url
is determined at the owner or site admin level.
List pre-receive hooks for a repository
List all pre-receive hooks that are enabled or testing for this repository as well as any disabled hooks that are allowed to be enabled at the repository level. Pre-receive hooks that are disabled at a higher level and are not configurable will not be listed.
get /repos/{owner}/{repo}/pre-receive-hooks
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
direction |
string | query |
One of desc |
sort |
string | query |
Default: created |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks', {
owner: 'octocat',
repo: 'hello-world',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
[
{
"id": 42,
"name": "Check Commits",
"enforcement": "disabled",
"configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}
]
Notes
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
☝️This header is required.get /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
owner |
string | path | |
repo |
string | path | |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
owner: 'octocat',
repo: 'hello-world',
pre_receive_hook_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"id": 42,
"name": "Check Commits",
"enforcement": "disabled",
"configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}
Notes
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
☝️This header is required.Update pre-receive hook enforcement for a repository
For pre-receive hooks which are allowed to be configured at the repo level, you can set enforcement
patch /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
owner |
string | path | |
repo |
string | path | |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
enforcement |
string | body |
The state of enforcement for the hook on this repository. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42 \
-d '{"enforcement":"enforcement"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
owner: 'octocat',
repo: 'hello-world',
pre_receive_hook_id: 42,
enforcement: 'enforcement',
mediaType: {
previews: [
'eye-scream'
]
}
})
Response
Status: 200 OK
{
"id": 42,
"name": "Check Commits",
"enforcement": "enabled",
"configuration_url": "https://github.example.com/api/v3/repos/octocat/hello-world/pre-receive-hooks/42"
}
Notes
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
☝️This header is required.Remove pre-receive hook enforcement for a repository
Deletes any overridden enforcement on this repository for the specified hook.
Responds with effective values inherited from owner and/or global level.
delete /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
This API is under preview and subject to change.See preview notice |
owner |
string | path | |
repo |
string | path | |
pre_receive_hook_id |
integer | path |
pre_receive_hook_id parameter |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.eye-scream-preview+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/pre-receive-hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/pre-receive-hooks/{pre_receive_hook_id}', {
owner: 'octocat',
repo: 'hello-world',
pre_receive_hook_id: 42,
mediaType: {
previews: [
'eye-scream'
]
}
})
Responds with effective values inherited from owner and/or global level.
Status: 200 OK
{
"id": 42,
"name": "Check Commits",
"enforcement": "disabled",
"configuration_url": "https://github.example.com/api/v3/orgs/octocat/pre-receive-hooks/42"
}
Notes
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
☝️This header is required.Users
The User Administration API allows you to suspend, unsuspend, promote, and demote users on your enterprise. It is only available to authenticated site administrators. Normal users will receive a 403
response if they try to access it.
get /admin/keys
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
direction |
string | query |
One of desc |
sort |
string | query |
Default: created |
since |
string | query |
Only show public keys accessed after the given time. |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/keys
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/keys')
Response
Status: 200 OK
[
{
"key": "2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234",
"id": 2,
"url": "https://api.github.com/user/keys/2",
"title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
"created_at": "2020-06-11T21:31:57Z",
"verified": false,
"read_only": false,
"last_used": "2020-06-11T22:31:57Z",
"user_id": 1,
"repository_id": 2
},
{
"key": "9Og8iYjAyymI9LvABpJerYrMxURPc8r+dB7TJyvv1234",
"id": 3,
"url": "https://api.github.com/user/keys/2",
"title": "ssh-rsa AAAAB3NzaC1yc2EAAA",
"created_at": "2020-06-11T21:31:57Z",
"verified": false,
"read_only": false,
"last_used": "2020-06-11T22:31:57Z",
"user_id": 1,
"repository_id": 2
}
]
delete /admin/keys/{key_ids}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
key_ids |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/keys/KEY_IDS
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/keys/{key_ids}', {
key_ids: 'key_ids'
})
Response
Status: 204 No Content
get /admin/tokens
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Code samples
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/tokens
JavaScript (@octokit/core.js)
await octokit.request('GET /admin/tokens')
Response
Status: 200 OK
[
{
"id": 2,
"url": "https://enterprise.octocat.com/api/v3/authorizations/2",
"app": {
"name": "My personal access token",
"url": "https://docs.github.com/enterprise/rest/reference/enterprise-admin#list-personal-access-tokens",
"client_id": "00000000000000000000"
},
"token": "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
"hashed_token": "23cffb2fab1b0a62747863eba88cb9327e561f2f7a0c8661c0d9b83146cb8d45",
"token_last_eight": "Ae178B4a",
"note": "My personal access token",
"note_url": null,
"created_at": "2019-04-24T21:49:02Z",
"updated_at": "2019-04-24T21:49:02Z",
"scopes": [
"admin:business",
"admin:gpg_key",
"admin:org",
"admin:org_hook",
"admin:pre_receive_hook",
"admin:public_key",
"admin:repo_hook",
"delete_repo",
"gist",
"notifications",
"repo",
"user",
"write:discussion"
],
"fingerprint": null
}
]
Delete a personal access token
Deletes a personal access token. Returns a 403 - Forbidden
status when a personal access token is in use. For example, if you access this endpoint with the same personal access token that you are trying to delete, you will receive this error.
delete /admin/tokens/{token_id}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
token_id |
integer | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/tokens/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/tokens/{token_id}', {
token_id: 42
})
Response
Status: 204 No Content
Create a user
If an external authentication mechanism is used, the login name should match the login name in the external system. If you are using LDAP authentication, you should also update the LDAP mapping for the user.
The login name will be normalized to only contain alphanumeric characters or single hyphens. For example, if you send "octo_cat"
as the login, a user named "octo-cat"
will be created.
If the login name or email address is already associated with an account, the server will return a 422
response.
post /admin/users
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
login |
string | body |
Required. The user's username. |
email |
string | body |
Required for built-in authentication. The user's email address. This parameter can be omitted when using CAS, LDAP, or SAML. For details on built-in and centrally-managed authentication, see the the GitHub authentication guide. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/users \
-d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users', {
login: 'login'
})
Response
Status: 201 Created
{
"login": "octocat",
"id": 1,
"node_id": "MDQ6VXNlcjE=",
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/followers",
"following_url": "https://api.github.com/users/octocat/following{/other_user}",
"gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
"starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
"subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events{/privacy}",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "User",
"site_admin": false
}
patch /admin/users/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path | |
login |
string | body |
Required. The user's new username. |
Code samples
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/users/USERNAME \
-d '{"login":"login"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /admin/users/{username}', {
username: 'username',
login: 'login'
})
Response
Status: 202 Accepted
{
"message": "Job queued to rename user. It may take a few minutes to complete.",
"url": "https://api.github.com/user/1"
}
Delete a user
Deleting a user will delete all their repositories, gists, applications, and personal settings. Suspending a user is often a better option.
You can delete any user account except your own.
delete /admin/users/{username}
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/users/USERNAME
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}', {
username: 'username'
})
Response
Status: 204 No Content
post /admin/users/{username}/authorizations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path | |
scopes |
array of strings | body |
A list of scopes. |
Code samples
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations \
-d '{"scopes":["scopes"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /admin/users/{username}/authorizations', {
username: 'username',
scopes: [
'scopes'
]
})
Response
Status: 201 Created
{
"id": 1,
"url": "https://api.github.com/authorizations/1",
"scopes": [
"public_repo"
],
"token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
"token_last_eight": "Ae178B4a",
"hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
"app": {
"url": "http://my-github-app.com",
"name": "my github app",
"client_id": "abcde12345fghij67890"
},
"note": "optional note",
"note_url": "http://optional/note/url",
"updated_at": "2011-09-06T20:39:23Z",
"created_at": "2011-09-06T17:26:27Z",
"fingerprint": "jklmnop12345678"
}
delete /admin/users/{username}/authorizations
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/admin/users/USERNAME/authorizations
JavaScript (@octokit/core.js)
await octokit.request('DELETE /admin/users/{username}/authorizations', {
username: 'username'
})
Response
Status: 204 No Content
Promote a user to be a site administrator
Note that you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP verbs."
put /users/{username}/site_admin
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/site_admin', {
username: 'username'
})
Response
Status: 204 No Content
delete /users/{username}/site_admin
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/users/USERNAME/site_admin
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/site_admin', {
username: 'username'
})
Response
Status: 204 No Content
Suspend a user
If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, Active Directory LDAP-authenticated users cannot be suspended through this API. If you attempt to suspend an Active Directory LDAP-authenticated user through this API, it will return a 403
response.
You can suspend any user account except your own.
Note that, if you choose not to pass any parameters, you'll need to set Content-Length
to zero when calling out to this endpoint. For more information, see "HTTP verbs."
put /users/{username}/suspended
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path | |
reason |
string | body |
The reason the user is being suspended. This message will be logged in the audit log. If you don't provide a |
Code samples
Shell
curl \
-X PUT \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/users/USERNAME/suspended \
-d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /users/{username}/suspended', {
username: 'username',
reason: 'reason'
})
Response
Status: 204 No Content
Unsuspend a user
If your GitHub instance uses LDAP Sync with Active Directory LDAP servers, this API is disabled and will return a 403
response. Active Directory LDAP-authenticated users cannot be unsuspended using the API.
delete /users/{username}/suspended
Parameters
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
username |
string | path | |
reason |
string | body |
The reason the user is being unsuspended. This message will be logged in the audit log. If you don't provide a |
Code samples
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/users/USERNAME/suspended \
-d '{"reason":"reason"}'
JavaScript (@octokit/core.js)
await octokit.request('DELETE /users/{username}/suspended', {
username: 'username',
reason: 'reason'
})
Response
Status: 204 No Content